Merge "Include terminology definition from docstring"

doc/source/conf.py

@@ -28,7 +28,8 @@ extensions = [
     'sphinxcontrib.httpdomain',
     'sphinxcontrib.pecanwsme.rest',
     'wsmeext.sphinxext',
-    'oslosphinx'
+    'oslosphinx',
+    'watcher.doc',
 ]
 
 wsme_protocols = ['restjson']

setup.cfg

@@ -48,6 +48,7 @@ watcher_strategies =
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build
+fresh_env = 1
 all_files = 1
 
 [upload_sphinx]

test-requirements.txt

@@ -2,19 +2,19 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
-hacking<0.11,>=0.10
 coverage>=3.6
 discover
-python-subunit>=0.0.18
+hacking>=0.10.2,<0.11
+mock>=1.2
 oslotest>=1.10.0  # Apache-2.0
+python-subunit>=0.0.18
 testrepository>=0.0.18
 testscenarios>=0.4
 testtools>=1.4.0
-mock>=1.2
 
 # Doc requirements
+oslosphinx>=2.5.0 # Apache-2.0
 sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
-oslosphinx>=2.5.0  # Apache-2.0
 sphinxcontrib-pecanwsme>=0.8
 
 # For PyPI distribution

watcher/doc.py

@@ -0,0 +1,86 @@
+# -*- encoding: utf-8 -*-
+# Copyright (c) 2015 b<>com
+#
+# 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.
+
+from __future__ import unicode_literals
+
+import importlib
+
+from docutils import nodes
+from docutils.parsers import rst
+from docutils import statemachine as sm
+
+from watcher.version import version_info
+
+import textwrap
+
+
+class WatcherTerm(rst.Directive):
+    """Directive to import an RST formatted docstring into the Watcher glossary
+
+    How to use it
+    -------------
+
+    # inside your .py file
+    class DocumentedObject(object):
+        '''My *.rst* docstring'''
+
+
+    # Inside your .rst file
+    .. watcher-term:: import.path.to.your.DocumentedObject
+
+    This directive will then import the docstring and then interprete it.
+    """
+
+    # You need to put an import path as an argument for this directive to work
+    required_arguments = 1
+
+    def add_textblock(self, textblock, *lineno):
+        for line in textblock.splitlines():
+            self.add_line(line)
+
+    def add_line(self, line, *lineno):
+        """Append one line of generated reST to the output."""
+        self.result.append(line, rst.directives.unchanged, *lineno)
+
+    def run(self):
+        self.result = sm.ViewList()
+
+        cls_path = self.arguments[0]
+
+        try:
+            module_name, obj_name = cls_path.rsplit(".", 1)
+            module = importlib.import_module(module_name)
+            cls = getattr(module, obj_name)
+        except Exception as exc:
+            raise self.error(exc)
+
+        self.add_class_docstring(cls)
+
+        node = nodes.paragraph()
+        node.document = self.state.document
+        self.state.nested_parse(self.result, 0, node)
+        return node.children
+
+    def add_class_docstring(self, cls):
+        # Added 4 spaces to align the first line with the rest of the text
+        # to be able to dedent it correctly
+        cls_docstring = textwrap.dedent("%s%s" % (" " * 4, cls.__doc__))
+        self.add_textblock(cls_docstring)
+
+
+def setup(app):
+    app.add_directive('watcher-term', WatcherTerm)
+    return {'version': version_info.version_string()}