GitHub source code links and syntax highlighting for Sphinx documentation
Project description
GitHub source code links and syntax highlighting for Sphinx documentation
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.
…
GitHub Source Code Links
Using sphinx.ext.linkcode, a View on GitHub link is added to the documentation of every class, method, function, and property:
They link to and highlight the corresponding code block in your GitHub repository:
📝 Note |
---|
These links can be styled with CSS and used with/instead of the links added by sphinx.ext.viewcode |
Syntax Highlighting
sphinx-github-style also contains a Pygments style to highlight code blocks 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
The name of the package’s top-level module. For this repo, it would be sphinx_github_style
Type: str
- linkcode_blob
The blob to link to on GitHub - any of "head", "last_tag", or "{blob}"
Type: str
Default: "head"
"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
The link to your GitHub repository formatted as https://github.com/user/repo
Type: str
Default: f"https://github.com/{html_context['github_user']}/{html_context['github_repo']}/{html_context['github_version']}"
If not provided, will attempt to create the link from the html_context dict
- linkcode_link_text
The text to use for the linkcode link
Type: str
Default: "View on GitHub"
- 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()
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx-github-style-1.1.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f4301ffd8dbce45bb10d79e8be5edcb96d593a29f8f139dc433b068e7d1272f1 |
|
MD5 | e0ccfe6db3bc57819061b96ae72f55a7 |
|
BLAKE2b-256 | 33d73fd1a68ccd11780ecf5bf8555c4812a9fc915c18da2ba2e7e230419e24a7 |
Hashes for sphinx_github_style-1.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 46453c80d327a7204fa984788902a0971cc170f0c439677cc6c55fa0cf077758 |
|
MD5 | 652b7c9b57a5c24abafd2883c88e6d9f |
|
BLAKE2b-256 | 2f71e1c5899d4729cdd939e54e99146e972690c9009a05c300a788058cbb9620 |