Open Stack

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)