Open Stack

Hi Kato,

On 2016-01-28  9:37, Kato, Tomoyuki <kato.tomoyuki at jp.fujitsu.com>
wrote:
>Hi Tanja,
>
>Cloud you explain more detailed background?
>To be honest, I don't understand the reason as of now.
>Your explanation seems to be almost technical reason about Sphinx XML
>Builder. In my understand, however, we don't use and generate XML any
>more, with a few exceptions.
>Why do we need to convert RST to XML?

No problem, I will try to clarify:

You (the OpenStack project) don't need to use XML any more, but we
(SUSE doc team) contribute directly to the upstream manuals now and
include two of the upstream guides with a product of ours that is based
on OpenStack.

(In the beginning, we wrote and maintained our own user manuals for
this product, but using the same license as the OpenStack project so you
(OpenStack) could take over and use any of the texts or the book
structure, which also happened).

Our (SUSE) tool chain is largely based on DocBook XML (and we generate
4 output formats for all of our product documentation). That's why we
use this conversion step from RST to DocBook now, which works fine
except for this one ID duplication that I explained below.

Therefore the change proposed in $SUBJECT (which is hopefully not
intrusive for you) would simply make my life easier. :) But if it
should be declined, it's also fine with me, then I will fix it in our
generated XML sources.

Thanks,
Tanja


On 2016-01-28  9:37 Kato, Tomoyuki <kato.tomoyuki at jp.fujitsu.com> wrote:
>Hi Tanja,
>
>Cloud you explain more detailed background?
>To be honest, I don't understand the reason as of now.
>Your explanation seems to be almost technical reason about Sphinx XML
>Builder. In my understand, however, we don't use and generate XML any
>more, with a few exceptions.
>Why do we need to convert RST to XML?
>
>Thanks,
>KATO Tomoyuki
>
>> Hi Darren, hi Kato, hi all,
>> 
>> as the following might have exceeded the limits of the comments on
>> review.openstack.org, I thought I'd rather post it to this list.
>> 
>> I'm contributing to the End User Guide and Admin User Guide and
>> we are generating XML from the RST sources (via Sphinx XML Builder)
>> and convert the resulting XML files to DocBook with a script.
>> 
>> The Sphinx XML Builder automatically generates IDs for each section
>> title (in addition to any IDs that might be set in the RST files) and
>> derives the automatically generated IDs from the title. For example,
>> if the title is 'Attach a volume to an instance', the Sphinx XML
>> builder transform it to the following ID:
>> 'attach-a-volume-to-an-instance'.
>> 
>> Due to the parallel structure of UI and CLI chapters in both user
>> guides, a lot of section titles appear twice, like for example
>> 'Attach a volume to an instance', which appears in both
>> 'cli_manage_volumes.rst' and 'dashboard_manage_volumes.rst' in the
>> End User Guide. (Let me add that our conversion script removes any
>> duplicate IDs from the resulting DocBook XML files _unless_ there is
>> a reference to a specific ID.)
>> 
>> Now for the End User Guide, we stumbled across the following:
>> 
>> There is a reference in 'cli_nova_launch_instance_from_volume.rst'
>> pointing to the section 'Attach a volume to an instance' in
>> 'cli_manage_volumes.rst', where the respective section has the
>> following ID in RST: '_Attach_a_volume_to_an_instance:'.
>> 
>> As the Sphinx XML builder ignores case sensitivity and transforms
>> this ID to 'attach-a-volume-to-an-instance' (all lowercase!), we
>> ended up with exactly the same ID being generated by Sphinx XML
>> builder for the section in the *UI* chapter (which has no ID in the
>> RST files so far).
>> 
>> And now DocBook has the same ID twice and cannot identify where the
>> reference (xref) contained in
>> 'cli_nova_launch_instance_from_volume.xml' should point to.
>> 
>> To remedy this problem (without having to solve it manually each
>> time we update the guides from the RST sources), I proposed the
>> change request now under discussion in $SUBJECT.
>> 
>> Alternatively, I could change the ID in 'cli_manage_volumes.rst' from
>> '_Attach_a_volume_to_an_instance:' to
>> '_attach_a_volume_to_an_instance_cli:' and change the reference in
>> 'cli_nova_launch_instance_from_volume.rst' accordingly, if you agree.
>> (But that seemed more intrusive to me, that's why I suggested the
>> change in https://review.openstack.org/273123 in the first place).
>> 
>> BTW, we are developing and hosting the conversion script on GH - if
>> anyone here should be interested in the way back from RST to DocBook
>> for any reason, just let me know and I will post the link here. :)
>> 
>> Kind regards,
>> 
>> Tanja Roth, Documentation
>> SUSE Linux GmbH
>> 
>> GF: Felix Imendörffer, Jane Smithard, Graham Norton
>> HRB 21284 (AG Nürnberg)
>> 
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>_______________________________________________
>OpenStack-docs mailing list
>OpenStack-docs at lists.openstack.org
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs