Sphinx Gitref
Keep your sphinx docs in sync with your code.
Adds a :gitref:`..` role to Sphinx to link to your code on GitHub, GitLab or
Bitbucket, and to make sure the references in your docs match the code.
Key features:
- Check code referenced in documentation still exists
- Check code hashes and alert when something has changed
- Link to source code on github
- Incorporate into tests or git hooks
Supports Python 3.7+
Quickstart
Installation
Install:
pip install sphinx-gitref
In your Sphinx conf.py, add sphinx_gitref to the extensions list:
extensions = [
...
'sphinx_gitref',
]
See Configuration for options to customise gitref's defaults.
In reStructuredText
You can then use the :gitref:`..` role to link to a file on GitHub, GitLab,
Bitbucket, or your own remote git service:
This file is :gitref:`README.rst`
For more information, see the :gitref:`project README <README.rst>`
or link to a variable, function or class in a python file::
The method which turns a reference into a line number
is :gitref:`sphinx_python/parse.py::python_to_lineno` -
this will raise a warning if the reference is not found.
Reference class attributes as you would in Python, such
as :gitref:`sphinx_python/git.py::Repo.path`.
Code hash checks
If the file, line number or code reference is not in your code, or if they code's hash does not match the hash in the database, your docs will fail to build.
You can check your references are up-to-date with::
sphinx-gitref check
When adding new references, or when referenced code has changed, you can update the hash database with::
sphinx-gitref update
See the documentation for more detailed usage instructions and options.
Metadata
Release files for sphinx-gitref 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sphinx_gitref-0.4.1.tar.gz | 17.7 kB | Without provenance | Details for sphinx_gitref-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sphinx_gitref-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for sphinx_gitref-0.4.1-py3-none-any.whl |
Total release size: 33.6 kB
Release files / sphinx_gitref-0.4.1.tar.gz
| Download URL | sphinx_gitref-0.4.1.tar.gz |
|---|---|
| Size | 17.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ec15a83265eda1a8ed7174a7fc5efd76ee18132bb9fbd0b60e1fd4fd416b268
|
|
BLAKE2b-256 checksum How to use checksums |
92f48dbb1e46b2ecd8d49f8e2369fdc17a186961251aeff202bd737e47ddb716
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.4
|
Release files / sphinx_gitref-0.4.1-py3-none-any.whl
| Download URL | sphinx_gitref-0.4.1-py3-none-any.whl |
|---|---|
| Size | 15.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b64f61dbade370f16703639528e08006b0cf946805960ca5ad14386b3c616489
|
|
BLAKE2b-256 checksum How to use checksums |
934a11aa6b31f47cfdbf4e11b91ae2981cee8717b68c81f240d7f75e8948aee4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.4
|
Security for sphinx-gitref 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.