sphinx-gitref 0.2.1

Installation

Install:

pip install sphinx-gitref

Modify your Sphinx conf.py:

1. Add sphinx_gitref to the extensions list in your Sphinx conf.py:

   extensions = [
       ...
       'sphinx_gitref',
   ]

2. Optional: Explicitly specify the remote URL.

   Gitref will try to detect your remote origin URL from the .git dir in your docs’ parent dir. If it can’t find it, or detects the wrong remote, you can set or override the remote URL explicitly with:

   gitref_remote_url = "https://github.com/username/repository.git"

3. Optional: Explicitly specify the branch to link to.

   Gitref will try to detect your current branch from the .git dir in your docs’ parent dir. If it can’t find it, or you’d like it to use a different branch, you can set or override it explicitly with:

   gitref_branch = "master"

4. Optional: Change the link label format when a coderef is provided without an explicit label, eg :gitref:`filename.py::coderef`

   Gitref defaults to using showing the coderef and dropping the filename. This can be overridden by setting a format string:

   gitref_label_format = "{filename} {coderef}"

Usage

The :gitref:`..` role supports the following features:

• :gitref:`path/to/filename`

• :gitref:`path/to/filename.py::coderef`

You can optionally use them with a text label:

• :gitref:`text <path/to/filename>`

• :gitref:`text <path/to/filename.py::coderef>`

where coderef is a Python class, function or variable. You can also refer to class attributes as you would in python, eg MyClass.attribute.

These will be replaced by a link to the code.

If you do not provide a coderef, gitref will just check that the file exists.

Where you provide a coderef, gitref will check that an object with that name exists in the code, and will add its line number to the link.

This file is :gitref:`README.rst`
For more information, see the :gitref:`project README <README.rst>`

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`.

from sphinx_github.remotes import Remote
class Gitea(Remote):
    remote_match = re.compile(r"^git@gitea.example.com:(?P<repo>.+?)\.git$")
    url_pattern = "https://gitea.example.com/{repo}/blob/{branch}/{filename}{line}"
    url_pattern_line = "#L{line}"

Contributing

Contributions are welcome by pull request.

They will be merged more quickly if they are provided with unit tests; to run tests locally with tox:

pip install tox
tox

Changelog