issues

Add links to GitHub issues and Pull Requests.

Enable sphinx_toolbox.issues by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.issues',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

:issue:

Role which shows a link to the given issue on GitHub.

If the issue exists, the link has a tooltip that shows the title of the issue.

Example

:issue:`1`

#1

You can also reference an issue in a different repository by adding the repository name inside <>.

:issue:`7680 <pytest-dev/pytest>`

pytest-dev/pytest#7680

:pull:

Role which shows a link to the given pull request on GitHub.

If the pull requests exists, the link has a tooltip that shows the title of the pull requests.

Example

:pull:`2`

#2

You can also reference a pull request in a different repository by adding the repository name inside <>.

:pull:`7671 <pytest-dev/pytest>`

pytest-dev/pytest#7671

Changed in version 2.4.0: issue and pull now show the repository name when the name differs from that configured in conf.py.

Changed in version 2.4.0: These directives are also available in the github domain.

The only difference between the issue and pull roles is in the URL. GitHub uses the same numbering scheme for issues and pull requests, and automatically redirects to the pull request if the user tries to navigate to an issue with that same number.

Caching

HTTP requests to obtain issue/pull request titles are cached for four hours.

To clear the cache manually, run:

python3 -m sphinx_toolbox

API Reference

Functions:

setup(app)

Setup sphinx_toolbox.issues.

setup(app)[source]

Setup sphinx_toolbox.issues.

New in version 1.0.0.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata