sphinxcontrib.issuetracker – Reference issues in issue trackers

A Sphinx extension to turn textual issue ids like #10 into real references to these issues in an issue tracker.

The extension is available under the terms of the BSD license, see License for more information.

Installation

This extension needs Sphinx 1.0 and Python 2.6 or newer. Python 3 is not (yet) supported.

Use pip to install this extension straight from the Python Package Index:

pip install sphinx-contrib.issuetracker

Operation

After configuring the tracker and the project (and possibly the tracker url), you can reference issues in the issue tracker with the issue role:

:issue:

Create a reference to the given issue. This role understands the standard cross-referencing syntax used by Sphinx.

An explicit title given to this role is interpreted as format string, which is formatted with the Issue object representing the referenced issue available by the key issue. You may use any attribute of the Issue object in your format string. Use this feature to include information about the referenced issue in the reference title. For instance, you might use :issue:`{issue.title} (#{issue.id}) <10>` to use the title and the id of the issue 10 as reference title.

New in version 0.9.

Information about the issue (like the title) is retrieved from the configured issue tracker. Aside of providing it for reference titles, the extension also uses this information to mark closed issues in HTML output by striking the reference text through. For this purpose, a stylesheet is added to the generated HTML.

You can provide your own styles for issue references by adding them to the .xref.issue and .xref.issue.closed selectors (the latter are closed issues). For instance, the following stylesheet uses red color for open, and green color for closed issues:

.xref.issue {
    color: green;
}

.xref.issue.closed {
    color: red;
}

Issue ids in plain text

If issuetracker_plaintext_issues is True, this extension also searches for issue ids like #10 in plain text and turns them into issue references. Issue ids in literal text (e.g. inline literals or code blocks) are ignored. The pattern used to extract issue ids from plain text can be configured using issuetracker_issue_pattern.

Configuration

General configuration

Add sphinxcontrib.issuetracker to the configuration value extensions to enable this extensions and configure the extension:

issuetracker

The issuetracker to use. As of now, the following trackers are supported:

issuetracker_project

The project inside the issue tracker or the project, to which the issue tracker belongs. Defaults to the value of project.

Note

In case of BitBucket and GitHub, the project name must include the name of the user or organization, the project belongs to. For instance, the project name of Sphinx itself is not just sphinx, but birkenfeld/sphinx instead. If the user name is missing, a ValueError will be raised when an issue is to be resolved the first time.

Changed in version 0.8: Project names must include the user name now.

issuetracker_url

The base url of the issue tracker:

issuetracker = 'jira'
issuetracker_url = 'https://studio.atlassian.com'

Required by all issue trackers which do not only have a single instance, but many different instances on many different sites.

New in version 0.8.

For instance, with the following configuration issue references in the documentation would refer to the Sphinx issue tracker:

issuetracker = 'bitbucket'
issuetracker_project = 'birkenfeld/sphinx'

Plaintext issues

issuetracker_plaintext_issues

If True (the default) issue references are extracted from plain text by turning issue ids like #10 into references to the corresponding issue. Issue ids in any kind of literal text (e.g. inline literals or code blocks) are ignored.

New in version 0.9.

By default the extension looks for issue references starting with a single dash, like #10. You can however change the pattern, which is used to find issue references:

issuetracker_issue_pattern

A regular expression, which is used to find and parse issue references. Defaults to r'#(\d+)'. If changed to r'gh-(\d+)' for instance, this extension would not longer recognize references like #10, but instead parse references like gh-10. The pattern must contain only a single group, which matches the issue id.

Normally the reference title will be the whole issue id. However you can also use a custom reference title:

issuetracker_title_template

A format string template for the title of references created from plaintext issue ids. The format string gets the Issue object corresponding to the referenced issue in the issue key, you may use any attributes of this object in your format string. You can for instance include the issue title and the issue id:

issuetracker_title_template = '{issue.title} ({issue.id})'

If unset, the whole text matched by issuetracker_issue_pattern is used as reference title.

New in version 0.9: Replaces issuetracker_expandtitle

Customization

If you use an issue tracker that is not supported by this extension, then set issuetracker to None or leave it unset, and connect your own callback to the event issuetracker-lookup-issue:

issuetracker-lookup-issue(app, tracker_config, issue_id)

Emitted if the issue with the given issue_id should be looked up in the issue tracker. Issue tracker configured is provided by tracker_config.

app is the Sphinx application object. tracker_config is the issuetracker configuration as TrackerConfig object. issue_id is the issue id as string.

A callback should return an Issue object containing the looked up issue, or None if it could not find the issue. In the latter case other callbacks connected to this event are be invoked by Sphinx.

Changed in version 0.8: Replaced project argument with tracker_config, changed return value from dictionary to Issue

Changed in version 0.9: Renamed from issuetracker-resolve-issue to issuetracker-lookup-issue

class sphinxcontrib.issuetracker.TrackerConfig

Issue tracker configuration.

This class provides configuration for trackers, and is passed as tracker_config arguments to callbacks of issuetracker-lookup-issue.

project

The project name as string

url

The url of the issue tracker as string without any trailing slash, or None, if there is no url configured for this tracker. See issuetracker_url.

New in version 0.8.

class sphinxcontrib.issuetracker.Issue

A namedtuple() providing issue information.

id

The issue id as string

If you are writing your own custom callback for issuetracker-lookup-issue, set this attribute to the issue_id that was given as argument.

url

An URL providing information about this issue.

This URL is used as hyperlink target in the generated documentation. Thus it should point to a webpage or something similar that provides human-readable information about an issue.

closed

True, if the issue is closed, False otherwise.

New in version 0.8.

Contribution and Development

Please report bugs and missing functionality (e.g. a tracker not being supported) to the issue tracker.

The source code of this extension is available in the sphinx-contrib repository. Feel free to clone this repository and add your changes to this extension. Patches and pull requests are always welcome!

Credits

sphinxcontrib-issuetracker is written and maintained by Sebastian Wiesner <lunaryorn@googlemail.com>

The following people, listed alphabetically, contributed to this extension or supported its development otherwise:

  • Ali-Akber Saifee – Expand title feature, Jira support
  • Denis Bilenko – Fixes to Google Code integration, reporting of issues
  • Michael Fladischer – Integration of DebianBTS, Debian packaging, testing, reporting of issues, general fixes

Many thanks for all contributions!