Usage and 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 keyissue
. You may use any attribute of theIssue
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 issue10
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
.