Sphinx Github Style

GitHub source code links and syntax highlighting for Sphinx docs

About

sphinx-github-style is a Sphinx extension that makes your docs look like and link to GitHub

…

GitHub Source Code Links

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

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

Note

These links can be used with/instead of the links added by sphinx.ext.viewcode

• They use a newly added linkcode-link class which can be styled using CSS

Syntax Highlighting

sphinx-github-style also contains a Pygments style to highlight code in your documentation 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

top_level

top_level

The name of the package’s top-level module. For this repo, it would be sphinx_github_style

Type

str

Default

Return value from get_top_level()

linkcode_blob

linkcode_blob

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

• 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"

Type

str

Default

"head"

linkcode_url

linkcode_url

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

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

Type

str

Default

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

linkcode_link_text

linkcode_link_text

The text to use for the linkcode link

Type

str

Default

"View on GitHub"

linkcode_resolve

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

Noteworthy Components

• TDKStyle - Pygments Style for syntax highlighting similar to Github Pretty Lights Dark Theme

• TDKMethLexer - Pygments Lexer to add syntax highlighting to methods

• get_linkcode_resolve() - to link to GitHub source code using sphinx.ext.linkcode

• add_linkcode_node_class() - adds a new linkcode-link class, allowing for CSS styling separately from viewcode links

• github_style.css - CSS styling for linkcode links (icon + text)