# 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.clear_github_linkcode_caches()

  Clear the internal caches for GitHub code linking.

  This is primarily intended for unit tests.

  Added in version 2.0.

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.

      Added in version 2.1.

  Returns:

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

  Return type:

    `str`