sphinx-github-style 1.2.1

GitHub source code links and syntax highlighting for Sphinx documentation

GitHub source code links and syntax highlighting for Sphinx documentation

Explore the docs »

About

sphinx-github-style is a Sphinx extension that links your documentation to GitHub source code. It also adds syntax highlighting for code blocks similar to GitHub’s pretty lights dark theme.

…

GitHub Source Code Links

Using sphinx.ext.linkcode, a View on GitHub link is added to the documentation of every class, method, function, and property:

They link to and highlight the corresponding code block in your GitHub repository:

📝 Note
These links can be styled with CSS and used with/instead of the links added by sphinx.ext.viewcode

Syntax Highlighting

sphinx-github-style also contains a Pygments style to highlight code blocks similar to GitHub:

Installation

To install using pip:

pip install sphinx-github-style

Configuration

Add the extension to your conf.py

extensions = [
    "sphinx_github_style",
]

Optional Configuration Variables

Add any (or none) of the following configuration variables to your conf.py

linkcode_blob

The blob to link to on GitHub - any of "head", "last_tag", or "{blob}"

Type: str

Default: "head"

• "head" (default): links to the most recent commit hash; if this commit is tagged, uses the tag instead

• "last_tag": links to the most recent commit tag on the currently checked out branch

• "blob": links to any blob you want, for example "master" or "v2.0.1"

linkcode_url

The link to your GitHub repository formatted as https://github.com/user/repo

Type: str

Default: f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"

• If not provided, will attempt to create the link from the html_context dict

linkcode_link_text

The text to use for the linkcode link

Type: str

Default: "View on GitHub"

linkcode_resolve

A linkcode_resolve() function to use when resolving the link target with sphinx.ext.linkcode

Type: Callable

Default: Return value from get_linkcode_resolve()