Merge pull request #638 from hartwork/issue-637-fix-docs-build-for-sphinx-3

doc: Unbundle sphinxcontrib_github_alt to fix build for Sphinx 3 (fixes #637)

3 files changed, 5 insertions, 157 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 755b0a4..c7c9589 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('sphinxext'))
+#sys.path.insert(0, os.path.abspath('sphinxext'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -26,7 +26,8 @@ sys.path.insert(0, os.path.abspath('sphinxext'))
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
-              'sphinx.ext.viewcode', 'github',  # for easy GitHub links
+              'sphinx.ext.viewcode',
+              'sphinxcontrib_github_alt',  # for easy GitHub links
               ]
 
 github_project_url = "https://github.com/pexpect/pexpect"
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 57ebb2d..b2c914e 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1 +1,3 @@
 ptyprocess
+sphinx
+sphinxcontrib_github_alt
diff --git a/doc/sphinxext/github.py b/doc/sphinxext/github.py
deleted file mode 100644
index 519e146..0000000
--- a/doc/sphinxext/github.py
+++ /dev/null
@@ -1,155 +0,0 @@
-"""Define text roles for GitHub
-
-* ghissue - Issue
-* ghpull - Pull Request
-* ghuser - User
-
-Adapted from bitbucket example here:
-https://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/bitbucket/sphinxcontrib/bitbucket.py
-
-Authors
--------
-
-* Doug Hellmann
-* Min RK
-"""
-#
-# Original Copyright (c) 2010 Doug Hellmann.  All rights reserved.
-#
-
-from docutils import nodes, utils
-from docutils.parsers.rst.roles import set_classes
-
-def make_link_node(rawtext, app, type, slug, options):
-    """Create a link to a github resource.
-
-    :param rawtext: Text being replaced with link node.
-    :param app: Sphinx application context
-    :param type: Link type (issues, changeset, etc.)
-    :param slug: ID of the thing to link to
-    :param options: Options dictionary passed to role func.
-    """
-
-    try:
-        base = app.config.github_project_url
-        if not base:
-            raise AttributeError
-        if not base.endswith('/'):
-            base += '/'
-    except AttributeError as err:
-        raise ValueError('github_project_url configuration value is not set (%s)' % str(err))
-
-    ref = base + type + '/' + slug + '/'
-    set_classes(options)
-    prefix = "#"
-    if type == 'pull':
-        prefix = "PR " + prefix
-    node = nodes.reference(rawtext, prefix + utils.unescape(slug), refuri=ref,
-                           **options)
-    return node
-
-def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Link to a 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.
-
-    :param name: The role name used in the document.
-    :param rawtext: The entire markup snippet, with role.
-    :param text: The text marked with the role.
-    :param lineno: The line number where rawtext appears in the input.
-    :param inliner: The inliner instance that called us.
-    :param options: Directive options for customization.
-    :param content: The directive content for customization.
-    """
-
-    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]
-    app = inliner.document.settings.env.app
-    #app.info('issue %r' % text)
-    if 'pull' in name.lower():
-        category = 'pull'
-    elif 'issue' in name.lower():
-        category = 'issues'
-    else:
-        msg = inliner.reporter.error(
-            'GitHub roles include "ghpull" and "ghissue", '
-            '"%s" is invalid.' % name, line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-    node = make_link_node(rawtext, app, category, str(issue_num), options)
-    return [node], []
-
-def ghuser_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Link to a GitHub user.
-
-    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.
-
-    :param name: The role name used in the document.
-    :param rawtext: The entire markup snippet, with role.
-    :param text: The text marked with the role.
-    :param lineno: The line number where rawtext appears in the input.
-    :param inliner: The inliner instance that called us.
-    :param options: Directive options for customization.
-    :param content: The directive content for customization.
-    """
-    app = inliner.document.settings.env.app
-    #app.info('user link %r' % text)
-    ref = 'https://www.github.com/' + text
-    node = nodes.reference(rawtext, text, refuri=ref, **options)
-    return [node], []
-
-def ghcommit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Link to a GitHub commit.
-
-    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.
-
-    :param name: The role name used in the document.
-    :param rawtext: The entire markup snippet, with role.
-    :param text: The text marked with the role.
-    :param lineno: The line number where rawtext appears in the input.
-    :param inliner: The inliner instance that called us.
-    :param options: Directive options for customization.
-    :param content: The directive content for customization.
-    """
-    app = inliner.document.settings.env.app
-    #app.info('user link %r' % text)
-    try:
-        base = app.config.github_project_url
-        if not base:
-            raise AttributeError
-        if not base.endswith('/'):
-            base += '/'
-    except AttributeError as err:
-        raise ValueError('github_project_url configuration value is not set (%s)' % str(err))
-
-    ref = base + text
-    node = nodes.reference(rawtext, text[:6], refuri=ref, **options)
-    return [node], []
-
-
-def setup(app):
-    """Install the plugin.
-    
-    :param app: Sphinx application context.
-    """
-    app.info('Initializing GitHub plugin')
-    app.add_role('ghissue', ghissue_role)
-    app.add_role('ghpull', ghissue_role)
-    app.add_role('ghuser', ghuser_role)
-    app.add_role('ghcommit', ghcommit_role)
-    app.add_config_value('github_project_url', None, 'env')
-    return