lunar.sphinx.ext.issuetracker – Reference issues in issue trackers

This extension parses textual issue references like #10, looks up the issue in the configured issue tracker, and includes a link to the issue.

Configuration

The extension is configured with the following configuration settings:

issuetracker

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

• github: The issue tracker of http://github.com. To use this issue tracker, lxml 2.0 or newer must be installed.
• bitbucket: The issue tracker of http://bitbucket.org. To use this issue tracker, either Python 2.6 or later must be used, or simplejson must be installed.
• launchpad: The issue tracker of http://launchpad.net. To use this issue tracker, launchpadlib must be installed.
• google code: The issue tracker of http://code.google.com. To use this issue tracker, Python 2.5 or newer is required.

issuetracker_project

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

issuetracker_user

The user account, to which the project belongs. Required by the following issue trackers:

• github
• bitbucket

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

issuetracker = 'bitbucket'
issuetracker_user = 'birkenfeld'
issuetracker_project = 'sphinx'

There are two more advanced configuration values:

issuetracker_issue_pattern

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

Customization

If you use an issue tracker, that is not supported by this extension, then set issuetracker to None or leave it unset, and create your own callback for the missing-reference event of Sphinx. This callback should handle all nodes whose reftype attribute is 'issue', and return None for all other nodes. For nodes whose reftype is 'issue' the issue id is available in the reftarget attribute.

You may want to use the following convenience function. It creates a callback that does all the node handling for you. The only thing, that is left to do for you, is to provide a function which returns metadata for a given issue id:

lunar.sphinx.ext.issuetracker.make_issue_reference_resolver(get_issue_information)

Create and return a function which serves as callback for the missing-reference event, and handles all pending references whose reftype is 'issue'.

If invoked, the function created by this function returns a reference node which points to the issue, or None if the issue reference could not be resolved.

get_issue_information must be a callable, accepting the follwing four arguments:

1. The issue tracker project as given to issuetracker_project
2. The issue tracker user name as given to issuetracker_user
3. The issue id
4. The sphinx build environment

It shall return a dictionary, which may contain the following items:

• 'uri': The uri to a website representing the issue. If missing, the created function returns None to indicate that it can’t resolve this issue.
• 'closed': If present and True, mark the issue as closed by adding the class issue-closed to the returned reference.