Table Of Contents

Previous topic

lunar.sphinx.ext.ansi – Parse ANSI control sequences

Next topic

lunar.sphinx.ext.epydoc – Epydoc crossreferences

This Page

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.


The extension is configured with the following configuration settings:


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

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

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:

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.


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:


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.