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 the internal caches for GitHub code linking. |
|
|
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
andgithub_scheme
arguments.- Parameters:
domain (
unicode
) – The autodoc domain being processed. This only accepts “py”, and comes from the originallinkcode_resolve()
call.info (
dict
) – Information on the item being linked to. This comes from the originallinkcode_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
ofunicode
, 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:
- 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.