Repository files navigation

A Sphinx extension for linking to your project's issue tracker. Includes roles for linking to issues, pull requests, user profiles, with built-in support for GitHub (though this works with other services).

For an example usage, check outmarshmallow's changelog, which makes use of the roles in this library.

pip install sphinx-issues

Addsphinx_issues toextensions in yourconf.py.

The extension has default values for GitHub projects.Add theissues_github_path config variable and you are goodto 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 projectissues_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="@"

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 theissues_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 onPyPI.

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

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

Credit goes to Jeff Forcier for his work on thereleases 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.

MIT licensed. See the bundledLICENSE file for more details.

• Remove :cwe: and :cve: roles, as these are officially included in Sphinx>=8.1.0.
• Support Python 3.9-3.13. Python 3.8 is no longer supported.

• Add :pypi: role for linking to PyPI projects (#144).Thanks @shenxianpeng for the suggestion and PR.

• Default to linking GH Sponsors for the :user: role (#129).Thanks @webknjaz for the suggestion.
• Support Python 3.8-3.12. Older versions are no longer supported.
• Backwards-incompatible: Remove__version__,__author__, and__license__ attributes.Useimportlib.metadata to read this metadata instead.

• Fix regression from 3.0.0: exception: 'in <string>' requires string as left operand, not type.

• The :commit: role now outputs with an @ prefix.
• Add configuration options for changing prefixes.
• Allow {group} to be specified within issues_uri, issues_pr_uri, issues_commit_uri, and

• Drop support for Python 2.7 and 3.5.
• Test against Python 3.8 to 3.10.
• Add:cwe: role for linking to CVEs onhttps://cwe.mitre.org.Thanks @hugovk for the PR.
• Add support for custom urls and separatorsIssue #93
• Allow custom titles for all rolesIssue #116
• Added setting issues_default_group_project as future replacement of issues_github_path, to reflect the now to universal nature of the extension

• Add:commit: role for linking to commits.
• Add support for linking to external repos.
• Test against Python 3.7.

• Add:cve: role for linking to CVEs onhttps://cve.mitre.org.

• Add:pr: role. Thanks @jnotham for the suggestion.
• Drop support for Python 3.4.

• RaiseValueError if neitherissues_uri norissues_github_path is set. Thanks @jnothman for the PR.
• Drop support for Python 2.6 and 3.3.

• setup returns metadata, preventing warnings about parallel reads and writes. Thanks @jfinkels for reporting.

• Support anchor text for:user: role. Thanks @jnothman for the suggestion and thanks @amueller for the PR.

• Add:user: role for linking to GitHub user profiles.

• Initial release.