beanbag_docutils.sphinx.ext.github

Sphinx extension to link to source code on GitHub.

This links to source code for modules, classes, etc. to the correct line on GitHub. This prevents having to bundle the source code along with the documentation, and better ties everything together.

Setup

To use this, you’ll need to import the module and define your own linkcode_resolve() in your conf.py:

from beanbag_docutils.sphinx.ext.github import github_linkcode_resolve

extensions = [
    ...
    'sphinx.ext.linkcode',
    ...
]

def linkcode_resolve(domain, info):
    return github_linkcode_resolve(
        domain=domain,
        info=info,
        allowed_module_names=['mymodule'],
        github_org_id='myorg',
        github_repo_id='myrepo',
        branch='master',
        source_prefix='src/')

source_prefix and allowed_module_names are optional. See the docs for github_linkcode_resolve() for more information.

Functions

clear_github_linkcode_caches()

Clear the internal caches for GitHub code linking.

github_linkcode_resolve(domain, info, ...[, ...])

Return a link to the source on GitHub for the given autodoc info.

beanbag_docutils.sphinx.ext.github.github_linkcode_resolve(domain, info, github_org_id, github_repo_id, branch, source_prefix='', allowed_module_names=[], *, github_url='https://github.com')

Return a link to the source on GitHub for the given autodoc info.

This takes some basic information on the GitHub project, branch, and what modules are considered acceptable, and generates a link to the approprite line on the GitHub repository browser for the class, function, variable, or other object.

Changed in version 2.1: Added github_host and github_scheme arguments.

Parameters:
  • domain (unicode) – The autodoc domain being processed. This only accepts “py”, and comes from the original linkcode_resolve() call.

  • info (dict) – Information on the item being linked to. This comes from the original linkcode_resolve() call.

  • github_org_id (unicode) – The GitHub organization ID.

  • github_repo_id (unicode) – The GitHub repository ID.

  • branch (unicode) – The branch used as a merge base to find the appropriate commit to link to. Callers may want to compute this off of the version number of the project, or some other information.

  • source_prefix (unicode, optional) – A prefix for any linked filename, in case the module is not at the top of the source tree.

  • allowed_module_names (list of unicode, optional) – The list of top-level module names considered valid for links. If provided, links will only be generated if residing somewhere in one of the provided module names.

  • github_url (str, optional) –

    The URL to the base of the GitHub server.

    New in version 2.1.

Returns:

The link to the source. This will be None if a URL couldn’t be calculated.

Return type:

str

beanbag_docutils.sphinx.ext.github.clear_github_linkcode_caches()

Clear the internal caches for GitHub code linking.

This is primarily intended for unit tests.

New in version 2.0.