README.rst

Sphinx Github Style

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()