Skip to main content

A Sphinx extension for linking to your project's issue tracker

Project description

PyPI badge Build status

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

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.

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

5.0.1 (2025-04-10)

  • Properly handle user and org names with symbols in them (#174). Thanks @ilan-gold for reporting and @flying-sheep for the PR.

5.0.0 (2024-10-11)

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

4.1.0 (2024-04-14)

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

4.0.0 (2024-01-19)

  • 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. Use importlib.metadata to read this metadata instead.

3.0.1 (2022-01-11)

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

3.0.0 (2022-01-10)

  • 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

2.0.0 (2022-01-01)

  • Drop support for Python 2.7 and 3.5.

  • Test against Python 3.8 to 3.10.

  • Add :cwe: role for linking to CVEs on https://cwe.mitre.org. Thanks @hugovk for the PR.

  • Add support for custom urls and separators Issue #93

  • Allow custom titles for all roles Issue #116

  • Added setting issues_default_group_project as future replacement of issues_github_path, to reflect the now to universal nature of the extension

1.2.0 (2018-12-26)

  • Add :commit: role for linking to commits.

  • Add support for linking to external repos.

  • Test against Python 3.7.

1.1.0 (2018-09-18)

1.0.0 (2018-07-14)

  • Add :pr: role. Thanks @jnotham for the suggestion.

  • Drop support for Python 3.4.

0.4.0 (2017-11-25)

  • Raise ValueError if neither issues_uri nor issues_github_path is set. Thanks @jnothman for the PR.

  • Drop support for Python 2.6 and 3.3.

0.3.1 (2017-01-16)

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

0.3.0 (2016-10-20)

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

0.2.0 (2014-12-22)

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

0.1.0 (2014-12-21)

  • Initial release.

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_issues-5.0.1.tar.gz (14.4 kB view details)

Uploaded Source

Built Distribution

sphinx_issues-5.0.1-py3-none-any.whl (8.2 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_issues-5.0.1.tar.gz.

File metadata

  • Download URL: sphinx_issues-5.0.1.tar.gz
  • Upload date:
  • Size: 14.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for sphinx_issues-5.0.1.tar.gz
Algorithm Hash digest
SHA256 6da131d4545af00be4b48ec7c4086ea82c1371a05116bbe5779f57cff34bf16a
MD5 1c258ed2f810fd43b2ab4b1825d97c35
BLAKE2b-256 3a62b55f1c482ce20acee71185dbebf0497a48d23b325b48925d95d5ce0e4666

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinx_issues-5.0.1.tar.gz:

Publisher: build-release.yml on sloria/sphinx-issues

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sphinx_issues-5.0.1-py3-none-any.whl.

File metadata

  • Download URL: sphinx_issues-5.0.1-py3-none-any.whl
  • Upload date:
  • Size: 8.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for sphinx_issues-5.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 58cdd94df25546fa96a224afc9df17063deffaf38336c4a694d2bf478aec75a4
MD5 291b024537a083792eea82df26e6f223
BLAKE2b-256 e922497d11c8198e00f45bffa6edc275066938dcec76c346facf40a72ff94222

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinx_issues-5.0.1-py3-none-any.whl:

Publisher: build-release.yml on sloria/sphinx-issues

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

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