From 5324dfe7de4da0e6befa7bb6991a8d27f147c003 Mon Sep 17 00:00:00 2001
From: Gauvain Pocentek <gauvain.pocentek@objectif-libre.com>
Date: Thu, 4 Sep 2014 18:24:45 +0200
Subject: [PATCH] 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               |  2 +
 os_doc_tools/sphinx/__init__.py |  0
 os_doc_tools/sphinx/hotref.py   | 65 +++++++++++++++++++++++++++++++++
 requirements.txt                |  1 +
 test-requirements.txt           |  1 -
 5 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 os_doc_tools/sphinx/__init__.py
 create mode 100644 os_doc_tools/sphinx/hotref.py

diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst
index bc27c58e..fe218350 100644
--- a/RELEASE_NOTES.rst
+++ b/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
 ------
diff --git a/os_doc_tools/sphinx/__init__.py b/os_doc_tools/sphinx/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/os_doc_tools/sphinx/hotref.py b/os_doc_tools/sphinx/hotref.py
new file mode 100644
index 00000000..afb8fc83
--- /dev/null
+++ b/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')
diff --git a/requirements.txt b/requirements.txt
index da304be6..734f5605 100644
--- a/requirements.txt
+++ b/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
diff --git a/test-requirements.txt b/test-requirements.txt
index 908fcbbf..62db970f 100644
--- a/test-requirements.txt
+++ b/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