# sphinxcontrib.issuetracker – Reference issues in issue trackers

A Sphinx extension to reference issues in an issue tracker.

The extension is available under the terms of the BSD license.

## Installation

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

    pip install sphinxcontrib-issuetracker

This extension requires Sphinx 1.1 and Python 2.6 or Python 3.1.

Note

Some builtin issue trackers do not support Python 3 currently. Refer to `issuetracker` for more information.

## Usage

Add this extension to `extensions` and configure the issue tracker to use and the project in your `conf.py`:

    extensions = ['sphinxcontrib.issuetracker']

    issuetracker = 'github'
    issuetracker_project = 'lunaryorn/sphinxcontrib-issuetracker'

Now issue references like `#10` are replaced with links to the issue tracker of this extension, unless the reference occurs in literal text like inline literals or code blocks.

You can disable this magic behaviour by setting `issuetracker_plaintext_issues` to `False`:

    issuetracker_plaintext_issues = False

Now textual references are no longer replaced. However, you can still explicitly reference issues with the `issue` role.

For more details refer to the Usage and operation and Configuration chapters. If this extension does not yet support the issue tracker you’re using, read the Customization chapter and implement support for your tracker.

## Support

Please report issues to the issue tracker if you have trouble, found a bug in this extension or lack support for a specific issue tracker, but respect the following rules:

- Check that the issue has not already been reported.
- Check that the issue is not already fixed in the `master` branch.
- Open issues with clear title and a detailed description in grammatically correct, complete sentences.

## Development

The source code is hosted on Github:

> git clone https://github.com/lunaryorn/sphinxcontrib-issuetracker

Please fork the repository and send pull requests with your fixes or cool new features, but respect the following rules:

- Read how to properly contribute to open source projects on GitHub.
- Use a topic branch to easily amend a pull request later, if necessary.
- Write good commit messages.
- Squash commits on the topic branch before opening a pull request.
- Respect PEP 8 (use pep8 to check your coding style compliance)
- Add unit tests
- Open a pull request that relates to but one subject with a clear title and description in grammatically correct, complete sentences.

## Credits

sphinxcontrib-issuetracker is written and maintained by Sebastian Wiesner <lunaryorn@gmail.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!

## Contents

- Usage and operation
  - Issue ids in plain text
- Configuration
  - General configuration
  - Plaintext issues
- Customization
  - Supporting classes
- Changelog
  - 0.11 (Jan 17, 2013)
  - 0.10.1 (Jun 19, 2012)
  - 0.10 (Jun 18, 2012)
  - 0.9 (Aug 31, 2011)
    - Incompatible changes
    - Other changes
  - 0.8 (Aug 24, 2011)
    - Incompatible changes
    - Other changes
  - 0.7.2 (Mar 10, 2011)
  - 0.7.1 (Jan 19, 2011)
  - 0.7 (Jan 08, 2011)
  - 0.6 (Jan 04, 2011)
  - 0.5.4 (Nov 15, 2010)
  - 0.5.3 (Nov 14, 2010)
  - 0.5.2 (Sep 17, 2010)
  - 0.5.1 (Jul 25, 2010)
  - 0.5 (Jul 21, 2010)
  - 0.4 (May 21, 2010)
  - 0.3 (May 02, 2010)
  - 0.2 (Apr 13, 2010)
  - 0.1 (Apr 10, 2010)