sphinx-github-role#
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:
extensions = [
# ...
"sphinx_github_role",
]
Basic usage#
MyST:
See {github}`astrojuanlu/sphinx-github-role#1`.
This project depends on {github}`sphinx-doc/sphinx`.
reStructuredText:
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:
github_default_org_project = ("astrojuanlu", None)
you can type this:
See {github}`sphinx-github-role#1`.
and with this configuration:
github_default_org_project = ("astrojuanlu", "sphinx-github-role")
you only need to type this:
See {github}`#1`.
For repository links, only the default_org
is relevant.
Customizing link text#
You can also customize the link text, by wrapping the target in angle brackets:
See {github}`this issue <#1>`.
Contribute#
Feel free to open an issue to report problems or suggest new features!