''' Simplify linking to Bokeh Github resources. This module proved four new roles that can be uses to easily link to various resources in the Bokeh Github repository: ``:bokeh-commit:`` : link to a specific commit ``:bokeh-issue:`` : link to an issue ``:bokeh-pull:`` : link to a pull request ``:bokeh-tree:`` : (versioned) link to a source tree URL Examples -------- The following code:: The repo history shows that :bokeh-commit:`bf19bcb` was made in in :bokeh-pull:`1698`, which closed :bokeh-issue:`1694`. This included updating all of the files in the :bokeh-tree:`examples` subdirectory. yields the output: The repo history shows that :bokeh-commit:`bf19bcb` was made in in :bokeh-pull:`1698`,which closed :bokeh-issue:`1694`. This included updating all of the files in the :bokeh-tree:`examples` subdirectory. ''' from __future__ import absolute_import from docutils import nodes, utils from docutils.parsers.rst.roles import set_classes BOKEH_GH = "https://github.com/bokeh/bokeh" def bokeh_commit(name, rawtext, text, lineno, inliner, options=None, content=None): ''' Link to a Bokeh Github issue. Returns 2 part tuple containing list of nodes to insert into the document and a list of system messages. Both are allowed to be empty. ''' app = inliner.document.settings.env.app node = _make_gh_link_node(app, rawtext, 'commit', 'commit ', 'commit', text, options) return [node], [] def bokeh_issue(name, rawtext, text, lineno, inliner, options=None, content=None): ''' Link to a Bokeh Github issue. Returns 2 part tuple containing list of nodes to insert into the document and a list of system messages. Both are allowed to be empty. ''' app = inliner.document.settings.env.app try: issue_num = int(text) if issue_num <= 0: raise ValueError except ValueError: msg = inliner.reporter.error( 'Github issue number must be a number greater than or equal to 1; ' '"%s" is invalid.' % text, line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] node = _make_gh_link_node(app, rawtext, 'issue', '#', 'issues', str(issue_num), options) return [node], [] def bokeh_pull(name, rawtext, text, lineno, inliner, options=None, content=None): ''' Link to a Bokeh Github issue. Returns 2 part tuple containing list of nodes to insert into the document and a list of system messages. Both are allowed to be empty. ''' app = inliner.document.settings.env.app try: issue_num = int(text) if issue_num <= 0: raise ValueError except ValueError: msg = inliner.reporter.error( 'Github pull request number must be a number greater than or equal to 1; ' '"%s" is invalid.' % text, line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] node = _make_gh_link_node(app, rawtext, 'pull', 'pull request ', 'pull', str(issue_num), options) return [node], [] def bokeh_tree(name, rawtext, text, lineno, inliner, options=None, content=None): ''' Link to a URL in the Bokeh GitHub tree, pointing to appropriate tags for releases, or to master otherwise. The link text is simply the URL path supplied, so typical usage might look like: .. code-block:: none All of the examples are located in the :bokeh-tree:`examples` subdirectory of your Bokeh checkout. Returns 2 part tuple containing list of nodes to insert into the document and a list of system messages. Both are allowed to be empty. ''' app = inliner.document.settings.env.app tag = app.env.config['version'] if '-' in tag: tag = 'master' url = "%s/tree/%s/%s" % (BOKEH_GH, tag, text) options = options or {} set_classes(options) node = nodes.reference( rawtext, text, refuri=url, **options) return [node], [] def _make_gh_link_node(app, rawtext, role, kind, api_type, id, options=None): ''' Return a link to a Bokeh Github resource. Args: app (Sphinx app) : current app rawtext (str) : text being replaced with link node. role (str) : role name kind (str) : resource type (issue, pull, etc.) api_type (str) : type for api link id : (str) : id of the resource to link to options (dict) : options dictionary passed to role function ''' url = "%s/%s/%s" % (BOKEH_GH, api_type, id) options = options or {} set_classes(options) node = nodes.reference( rawtext, kind + utils.unescape(id), refuri=url, **options) return node def setup(app): app.add_role('bokeh-commit', bokeh_commit) app.add_role('bokeh-issue', bokeh_issue) app.add_role('bokeh-pull', bokeh_pull) app.add_role('bokeh-tree', bokeh_tree)