sphinx-github-style 1.0.3

Sphinx Github Integration and Github Dark Theme Pygments Style

GitHub source code links and syntax highlighting for Sphinx docs

Explore the 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 of the following configuration variables to your conf.py

linkcode_blob

linkcode_blob: str = "head"

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"

…

linkcode_url

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

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

…

linkcode_link_text

linkcode_link_text: str = "View on GitHub"

The text to use for the linkcode link

…

linkcode_resolve

linkcode_resolve: Callable

A linkcode_resolve() function to use for resolving the link target

• Uses default function from get_linkcode_resolve() if not specified (recommended)

Noteworthy Components

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

• TDKMethLexer - Pygments Lexor 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)

Documentation

Full documentation can be found on ReadTheDocs