sphinx-issues 6.0.0

Example

For an example usage, check out marshmallow’s changelog, which makes use of the roles in this library.

Installation and Configuration

pip install sphinx-issues

Add sphinx_issues to extensions in your conf.py.

The extension has default values for GitHub projects. Add the issues_github_path config variable and you are good to go:

# docs/conf.py

# ...
extensions = [
    # ...
    "sphinx_issues"
]

# Path to GitHub repo {group}/{project}  (note that `group` is the GitHub user or organization)
issues_github_path = "sloria/marshmallow"

# which is the equivalent to:
issues_uri = "https://github.com/{group}/{project}/issues/{issue}"
issues_prefix = "#"
issues_pr_uri = "https://github.com/{group}/{project}/pull/{pr}"
issues_pr_prefix = "#"
issues_commit_uri = "https://github.com/{group}/{project}/commit/{commit}"
issues_commit_prefix = "@"
issues_user_uri = "https://github.com/{user}"
issues_user_prefix = "@"

You can also use this extension with other issue trackers. Here is how you could configure it for a hosted GitLab instance:

# docs/conf.py

# ...
extensions = [
    # ...
    "sphinx_issues"
]

#  Default repo {group}/{project} of gitlab project
issues_default_group_project = "myteam/super_great_project"
issues_uri = "https://gitlab.company.com/{group}/{project}/-/issues/{issue}"
issues_prefix = "#"
issues_pr_uri = "https://gitlab.company.com/{group}/{project}/-/merge_requests/{pr}"
issues_pr_prefix = "!"
issues_commit_uri = "https://gitlab.company.com/{group}/{project}/-/commit/{commit}"
issues_commit_prefix = "@"
issues_user_uri = "https://gitlab.company.com/{user}"
issues_user_prefix = "@"

Usage inside the documentation

Use the :issue: and :pr: roles in your docs like so:

See issue :issue:`42`

See issues :issue:`12,13`

See :issue:`sloria/konch#45`.

See PR :pr:`58`

The :user: role links to user profiles (GitHub by default, but can be configured via the issues_user_uri config variable).

The :commit: role links to commits.

Fixed in :commit:`6bb9124d5e9dbb2f7b52864c3d8af7feb1b69403`.

Thanks to :user:`bitprophet` for the idea!

You can also change the text of the hyperlink:

This change is due to :user:`Andreas Mueller <amueller>`.

The syntax :role:`My custom title <target>` works for all roles of this extension.

Fix bad bug :issue:`123, 199 (Duplicate) <123>`

The :pypi: role links to project pages on PyPI.

:pypi:`sphinx-issues` - A Sphinx extension for linking to your project's issue tracker.

Important note about :cwe: and :cve: roles

The :cwe: and :cve: are included within newer versions of Sphinx. If you use these roles and are using Sphinx<8.1, you will need to install sphinx-issues<5.

Sphinx version support policy

We support the latest released version of Sphinx that is older than 1 year. We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed.

Credits

Credit goes to Jeff Forcier for his work on the releases extension, which is a full-featured solution for generating changelogs. I just needed a quick way to reference GitHub issues in my docs, so I yoinked the bits that I needed.

License

MIT licensed. See the bundled LICENSE file for more details.

Changelog