A Sphinx extension for linking to your project's issue tracker
Project description
A Sphinx extension for linking to your project’s issue tracker. Includes roles for linking to both issues and 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. If your project is on Github, add the issues_github_path config variable. Otherwise, use issues_uri.
# docs/conf.py
#...
extensions = [
#...
'sphinx_issues',
]
# Github repo
issues_github_path = 'sloria/marshmallow'
# equivalent to
issues_uri = 'https://github.com/sloria/marshmallow/issues/{issue}'
Usage
Use the :issue: role in your docs like so:
See issue :issue:`42`
See issues :issue:`12,13`
Use the :user: role in your docs to link to user profiles (Github by default, but can be configured via the issues_user_uri config variable).
Thanks to :user:`bitprophet` for the idea!
You can also use explicit names if you want to use a different name than the github user name:
This change is due to :user:`Andreas Mueller <amueller>`.
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
0.4.0 (2017-11-25)
Raise ValueError if neither issues_uri nor issues_github_path is set. Thanks @jnothman for the PR.
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_issues-0.4.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f9741be540be92d6a5330ddb54506a4a2860ed07890635f0beb4c5eed19f65f4 |
|
MD5 | 06287296a7e6725aae3bd52e3f9b4fe4 |
|
BLAKE2b-256 | 3a60dbe19e0e400ad5ea19d68a51127923f92759edd020f9ad22b68db29e52a1 |