[MRG] DOC :issue: role to simplify what's news (scikit-learn#7657)

Author: jnothman

doc/conf.py

@@ -35,6 +35,7 @@
     'numpy_ext.numpydoc',
     'sphinx.ext.linkcode', 'sphinx.ext.doctest',
     'sphinx_gallery.gen_gallery',
+    'sphinx_issues',
 ]
 
 # pngmath / imgmath compatibility layer for different sphinx versions
@@ -269,6 +270,13 @@ def make_carousel_thumbs(app, exception):
             sphinx_gallery.gen_rst.scale_image(image, c_thumb, max_width, 190)
 
 
+# Config for sphinx_issues
+
+issues_uri = 'https://github.com/scikit-learn/scikit-learn/issues/{issue}'
+issues_github_path = 'scikit-learn/scikit-learn'
+issues_user_uri = 'https://github.com/{user}'
+
+
 def setup(app):
     # to hide/show the prompt in code examples:
     app.add_javascript('js/copybutton.js')

doc/sphinxext/sphinx_issues.py

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+"""A Sphinx extension for linking to your project's issue tracker."""
+"""
+Copyright 2014 Steven Loria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+"""
+
+try:
+    from docutils import nodes, utils
+except ImportError:
+    # Load lazily so that test-sphinxext does not require docutils dependency
+    pass
+
+__version__ = '0.2.0'
+__author__ = 'Steven Loria'
+__license__ = 'MIT'
+
+
+def user_role(name, rawtext, text, lineno,
+              inliner, options=None, content=None):
+    """Sphinx role for linking to a user profile. Defaults to linking to
+    Github profiles, but the profile URIS can be configured via the
+    ``issues_user_uri`` config value.
+
+    Example: ::
+
+        :user:`sloria`
+    """
+    options = options or {}
+    content = content or []
+    username = utils.unescape(text).strip()
+    config = inliner.document.settings.env.app.config
+    if config.issues_user_uri:
+        ref = config.issues_user_uri.format(user=username)
+    else:
+        ref = 'https://github.com/{0}'.format(username)
+    text = '@{0}'.format(username)
+    link = nodes.reference(text=text, refuri=ref, **options)
+    return [link], []
+
+
+def _make_issue_node(issue_no, config, options=None):
+    options = options or {}
+    if issue_no not in ('-', '0'):
+        if config.issues_uri:
+            ref = config.issues_uri.format(issue=issue_no)
+        elif config.issues_github_path:
+            ref = 'https://github.com/{0}/issues/{1}'.format(
+                config.issues_github_path, issue_no
+            )
+        issue_text = '#{0}'.format(issue_no)
+        link = nodes.reference(text=issue_text, refuri=ref, **options)
+    else:
+        link = None
+    return link
+
+
+def issue_role(name, rawtext, text, lineno,
+               inliner, options=None, content=None):
+    """Sphinx role for linking to an issue. Must have
+    `issues_uri` or `issues_github_path` configured in ``conf.py``.
+
+    Examples: ::
+
+        :issue:`123`
+        :issue:`42,45`
+    """
+    options = options or {}
+    content = content or []
+    issue_nos = [each.strip() for each in utils.unescape(text).split(',')]
+    config = inliner.document.settings.env.app.config
+    ret = []
+    for i, issue_no in enumerate(issue_nos):
+        node = _make_issue_node(issue_no, config, options=options)
+        ret.append(node)
+        if i != len(issue_nos) - 1:
+            sep = nodes.raw(text=', ', format='html')
+            ret.append(sep)
+    return ret, []
+
+
+def setup(app):
+    # Format template for issues URI
+    # e.g. 'https://github.com/sloria/marshmallow/issues/{issue}
+    app.add_config_value('issues_uri', default=None, rebuild='html')
+    # Shortcut for Github, e.g. 'sloria/marshmallow'
+    app.add_config_value('issues_github_path', default=None, rebuild='html')
+    # Format template for user profile URI
+    # e.g. 'https://github.com/{user}'
+    app.add_config_value('issues_user_uri', default=None, rebuild='html')
+    app.add_role('issue', issue_role)
+    app.add_role('user', user_role)