Sphinx GitHub Style: GitHub Integration and Pygments Style for Sphinx Documentation

Sphinx Github Style

GitHub source code links and syntax highlighting for Sphinx documentation

PyPI Version GitHub Repository https://static.pepy.tech/personalized-badge/sphinx-github-style?period=total&units=none&left_color=grey&right_color=blue&left_text=Downloads Documentation Status


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.

Syntax Highlighting

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

def get_repo_dir() -> Path:
    """Returns the root directory of the repository

    :return: A Path object representing the working directory of the repository.
    """
    try:
        cmd = "git rev-parse --show-toplevel"
        repo_dir = Path(subprocess.check_output(cmd.split(" ")).strip().decode('utf-8'))

    except subprocess.CalledProcessError as e:
        raise RuntimeError("Unable to determine the repository directory") from e

    return repo_dir

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

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