Provide the hotref sphinx extension

This extension simplifies the generation of hyperlinks referencing HOT
resources in the hot-reference book. It will be used in the hot-guide.

Change-Id: I382b5960733bec9b96924475887b02c8b1b01ea6
Implements: blueprint heat-templates

RELEASE_NOTES.rst

@@ -12,6 +12,8 @@ Release notes
   setup, add support for the ``create`` subcommand, add support for
   offline/fast operation.
 * ``diff_branches.py``: Updated output format.
+* Provide a ``hotref`` extension for sphinx, to automate the creation of
+  references to the HOT resources documentation.
 
 0.18.1
 ------

os_doc_tools/sphinx/hotref.py

@@ -0,0 +1,65 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""Sphinx extension to create references to the HOT reference resources.
+
+    This extension provides some inline markup to automatically generate links
+    to the OpenStack HOT reference resources.
+
+    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."""
+
+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], []
+
+
+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')

requirements.txt

@@ -8,3 +8,4 @@ Babel>=1.3
 iso8601>=0.1.9
 lxml>=2.3
 oslo.config>=1.4.0.0a3
+sphinx>=1.1.2,!=1.2.0,<1.3

test-requirements.txt

@@ -7,4 +7,3 @@ doc8  # Apache-2.0
 # Hacking already pins down pep8, pyflakes and flake8
 hacking>=0.9.2,<0.10
 pylint==0.25.2
-sphinx>=1.1.2,!=1.2.0,<1.3