Open Stack

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