sphinx-github-role#

Documentation Status Code style: black PyPI

A github role for Sphinx.

Installation#

To install, run

(.venv) $ pip install sphinx-github-role

Usage#

Adding the extension to your configuration file#

For any functionality to work, you first need to add "sphinx_github_role" to your list of extensions in the Sphinx configuration file (conf.py). For example:

conf.py#
extensions = [
    # ...
    "sphinx_github_role",
]

Basic usage#

MyST:

index.md#
See {github}`astrojuanlu/sphinx-github-role#1`.
This project depends on {github}`sphinx-doc/sphinx`.

reStructuredText:

index.rst#
See :github:`astrojuanlu/sphinx-github-role#1`.
This project depends on :github:`sphinx-doc/sphinx`.

Configuring a default organization and project#

The extension accepts a configuration github_default_org_project that can be a tuple ("default_org", "default_project") to save some typing. For example, with this configuration:

conf.py#
github_default_org_project = ("astrojuanlu", None)

you can type this:

index.md#
See {github}`sphinx-github-role#1`.

and with this configuration:

conf.py#
github_default_org_project = ("astrojuanlu", "sphinx-github-role")

you only need to type this:

index.md#
See {github}`#1`.

For repository links, only the default_org is relevant.

Contribute#

Feel free to open an issue to report problems or suggest new features!