add sphinx extension

set up extras for the dependency on sphinx to use the extension, and use
those in the test requirements in tox.ini instead of listing sphinx in
test-requirements.txt

add a page to the docs with release notes for reno itself

Change-Id: I0fd98c128ccf32bb85ad7189ee78c1b98933ae41

doc/source/conf.py

@@ -23,7 +23,8 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'oslosphinx',
+    'reno.sphinxext',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy

doc/source/history.rst

@@ -0,0 +1 @@
+.. release-notes:: Release Notes

doc/source/index.rst

@@ -15,6 +15,7 @@ Contents:
    installation
    usage
    contributing
+   history
 
 Indices and tables
 ==================

releasenotes/notes/4a092b4102370246-sphinx-extension.yaml

@@ -0,0 +1,3 @@
+---
+features:
+  - Add the sphinx extension for integration with documentation builds.

reno/sphinxext.py

@@ -0,0 +1,84 @@
+# 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.
+
+import os.path
+
+from reno import defaults
+from reno import formatter
+from reno import scanner
+
+from docutils import nodes
+from docutils.parsers import rst
+from docutils.parsers.rst import directives
+from docutils.statemachine import ViewList
+from sphinx.util.nodes import nested_parse_with_titles
+
+
+class ReleaseNotesDirective(rst.Directive):
+
+    has_content = True
+
+    option_spec = {
+        'branch': directives.unchanged,
+        'reporoot': directives.unchanged,
+        'relnotessubdir': directives.unchanged,
+        'notesdir': directives.unchanged,
+        'version': directives.unchanged,
+    }
+
+    def run(self):
+        env = self.state.document.settings.env
+        app = env.app
+
+        def info(msg):
+            app.info('[reno] %s' % (msg,))
+
+        title = ' '.join(self.content)
+        branch = self.options.get('branch')
+        reporoot_opt = self.options.get('reporoot', '.')
+        reporoot = os.path.abspath(reporoot_opt)
+        relnotessubdir = self.options.get('relnotessubdir',
+                                          defaults.RELEASE_NOTES_SUBDIR)
+        notessubdir = self.options.get('notesdir', defaults.NOTES_SUBDIR)
+        version_opt = self.options.get('version')
+
+        notesdir = os.path.join(relnotessubdir, notessubdir)
+        info('scanning %s for %s release notes' %
+             (os.path.join(reporoot, notesdir), branch or 'current branch'))
+
+        notes = scanner.get_notes_by_version(reporoot, notesdir, branch)
+        if version_opt is not None:
+            versions = [
+                v.strip()
+                for v in version_opt.split(',')
+            ]
+        else:
+            versions = notes.keys()
+        text = formatter.format_report(
+            reporoot,
+            notes,
+            versions,
+            title=title,
+        )
+        source_name = '<' + __name__ + '>'
+        result = ViewList()
+        for line in text.splitlines():
+            result.append(line, source_name)
+
+        node = nodes.section()
+        node.document = self.state.document
+        nested_parse_with_titles(self.state, result, node)
+        return node.children
+
+
+def setup(app):
+    app.add_directive('release-notes', ReleaseNotesDirective)

setup.cfg

@@ -27,6 +27,10 @@ packages =
 console_scripts =
     reno = reno.main:main
 
+[extras]
+sphinx =
+  sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build

test-requirements.txt

@@ -7,7 +7,6 @@ hacking<0.11,>=0.10.0
 coverage>=3.6
 discover
 python-subunit>=0.0.18
-sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
 oslosphinx>=2.5.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18

tox.ini

@@ -8,7 +8,9 @@ usedevelop = True
 install_command = pip install -U {opts} {packages}
 setenv =
    VIRTUAL_ENV={envdir}
-deps = -r{toxinidir}/test-requirements.txt
+deps =
+    -r{toxinidir}/test-requirements.txt
+    .[sphinx]
 commands = python setup.py test --slowest --testr-args='{posargs}'
 
 [testenv:pep8]