dn2osdbk: handle internal references

The internal references were not properly created. This patches make the
:ref: inline markup create a <xref> tag when the reference is internal.

This patch also reworks the sphinx extension to handle the URLs that
will be generated in the hot-reference with the new :ref: behavior.

Closes-Bug: #1378073
Change-Id: I84bf268dc1055dc6b39f23c4415734184ec57eec
This commit is contained in:
Gauvain Pocentek 2014-10-11 07:29:11 +02:00
parent 9e0b746c76
commit f24863cf4d
4 changed files with 42 additions and 45 deletions

View File

@ -5,6 +5,7 @@ Release notes
----
* ``openstack-doc-test``: Check for a ``\n`` in the last line of a file.
* ``openstack-dn2osdbk``: Properly handle internal references.
0.19
----

View File

@ -15,6 +15,7 @@
import argparse
import glob
import os
import re
import sys
from lxml import etree
@ -63,20 +64,21 @@ class XMLFileTransformer(object):
root.insert(0, comment)
for item in tree.iter():
# Find tags with an 'id' attribute, and prefix its value with the
# basename of the file being processed. This avoids id conflicts
# when working with multiple source files.
# Find tags with an 'id' attribute. In case there are multiple
# space-separated IDs, we have to make a choice.
id_attrib = '%sid' % XML_NS
id = item.get(id_attrib)
if id is not None:
id = id.split(' ')[-1]
id = "%s_%s" % (self.basename, id)
item.attrib[id_attrib] = id
xml_id = item.get(id_attrib)
if xml_id is not None:
id_list = xml_id.split(' ')
# If the title and an associated reference target match, sphinx
# generates a second id like 'id[0-9]' which is hardly usable.
# So we take the first id in that case, otherwise the last.
if len(id_list) > 1 and re.match(r'id\d+', id_list[-1]):
xml_id = id_list[0]
else:
xml_id = id_list[-1]
# Same for the linkend attribute.
linkend = item.get('linkend')
if linkend is not None:
item.attrib['linkend'] = "%s_%s" % (self.basename, linkend)
item.attrib[id_attrib] = xml_id
return tree

View File

@ -545,12 +545,25 @@ HYPERLINK & FOOTNOTES
<xsl:template match="reference">
<xsl:choose>
<xsl:when test="@refuri">
<link>
<xsl:attribute name="xlink:href">
<xsl:value-of select="@refuri"/>
</xsl:attribute>
<xsl:apply-templates/>
</link>
<xsl:choose>
<xsl:when test="@internal='True'">
<xref>
<xsl:attribute name="linkend">
<xsl:value-of select="substring-after(@refuri, '#')"/>
</xsl:attribute>
<!-- Don't apply-templates here or invalid docbook will
be generated (<emphasis> in <xref>). -->
</xref>
</xsl:when>
<xsl:otherwise>
<link>
<xsl:attribute name="xlink:href">
<xsl:value-of select="@refuri"/>
</xsl:attribute>
<xsl:apply-templates/>
</link>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:when test="@refid">
<link>

View File

@ -18,9 +18,6 @@
Usage examples:
The :hotref:`OS::Nova::Server` resource creates a new instance.
The :hotref:os:`OS::Nova:Server` resource also.
The :hotref:cfn:`AWS::CloudFormation::WaitCondition` is an AWS
resource.
To use this extension, add 'os_doc_tools.sphinx.hotref' in the `extensions`
list of your conf.py file."""
@ -29,37 +26,21 @@ from docutils import nodes
from docutils import utils
def build_ref_node(prefix, rawtext, app, resource, options):
link = resource.replace(':', '_')
base = app.config.hotref_base_url
ref = "%(base)s/%(prefix)s_%(name)s.html" % {'base': base,
'prefix': prefix,
'name': link}
literal = nodes.literal('')
ref_node = nodes.reference(rawtext, utils.unescape(resource),
refuri=ref, **options)
literal.append(ref_node)
return literal
def hotref_os_role(name, rawtext, text, lineno, inliner, options={},
content=[]):
app = inliner.document.settings.env.app
node = build_ref_node('openstack', rawtext, app, text, options)
return [node], []
def hotref_cfn_role(name, rawtext, text, lineno, inliner, options={},
content=[]):
app = inliner.document.settings.env.app
node = build_ref_node('cfn', rawtext, app, text, options)
return [node], []
link = text.replace(':', '_')
base = app.config.hotref_base_url
ref = "%(base)s/%(name)s.html" % {'base': base, 'name': link}
literal = nodes.literal('')
ref_node = nodes.reference(rawtext, utils.unescape(text),
refuri=ref, **options)
literal.append(ref_node)
return [literal], []
def setup(app):
app.add_role('hotref', hotref_os_role)
app.add_role('hotref:os', hotref_os_role)
app.add_role('hotref:cfn', hotref_cfn_role)
app.add_config_value('hotref_base_url',
'http://docs.openstack.org/hot-reference/content',
'env')