.. highlight:: rest

:mod:`lunar.sphinx.ext.issuetracker` -- Reference issues in issue trackers
==========================================================================

.. module:: lunar.sphinx.ext.issuetracker
   :synopsis: Parse issue references and link to the corresponding issues


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:

.. confval:: 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.

.. confval:: issuetracker_project

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

.. confval:: 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`_:

.. code-block:: python

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

There are two more advanced configuration values:

.. confval:: 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 :confval:`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:

.. autofunction:: make_issue_reference_resolver


.. _`Sphinx issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues/
.. _`lxml`: http://codespeak.net/lxml
.. _`simplejson`: http://pypi.python.org/pypi/simplejson/
.. _`launchpadlib`: http://pypi.python.org/pypi/launchpadlib/