Skip to main content

Keep your sphinx docs in sync with your code.

Project description

Sphinx Gitref

PyPI Documentation Tests Coverage

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_gitref-0.4.1.tar.gz (17.7 kB view hashes)

Uploaded Source

Built Distribution

sphinx_gitref-0.4.1-py3-none-any.whl (15.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page