Metadata-Version: 2.1
Name: sphinx-issues
Version: 1.0.0
Summary: A Sphinx extension for linking to your project's issue tracker
Home-page: https://github.com/sloria/sphinx-issues
Author: Steven Loria
Author-email: sloria1@gmail.com
License: MIT
Project-URL: Issues, https://github.com/sloria/sphinx-issues/issues
Keywords: sphinx issues github
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: sphinx

=============
sphinx-issues
=============

.. image:: https://travis-ci.org/sloria/sphinx-issues.svg?branch=master
    :target: https://travis-ci.org/sloria/sphinx-issues

A Sphinx extension for linking to your project's issue tracker. Includes roles for linking to issues, pull requests, user profiles, with built-in support for GitHub (though this works with other services).

Example
*******

For an example usage, check out `marshmallow's changelog <http://marshmallow.readthedocs.org/en/latest/changelog.html>`_, which makes use of the roles in this library.

Installation and Configuration
******************************

.. code-block:: console

    pip install sphinx-issues


Add ``sphinx_issues`` to ``extensions`` in your ``conf.py``. If your project is on GitHub, add the ``issues_github_path`` config variable. Otherwise, use ``issues_uri`` and ``issues_pr_uri``.

.. code-block:: python

    # docs/conf.py

    #...
    extensions = [
        #...
        'sphinx_issues',
    ]

    # Github repo
    issues_github_path = 'sloria/marshmallow'

    # equivalent to
    issues_uri = 'https://github.com/sloria/marshmallow/issues/{issue}'
    issues_pr_uri = 'https://github.com/sloria/marshmallow/pull/{pr}'

Usage
*****

Use the ``:issue:``  and ``:pr:`` roles in your docs like so:

.. code-block:: rst

    See issue :issue:`42`

    See issues :issue:`12,13`

    See PR :pr:`58`


Use the ``:user:`` role in your docs to link to user profiles (Github by default, but can be configured via the ``issues_user_uri`` config variable).

.. code-block:: rst

    Thanks to :user:`bitprophet` for the idea!

You can also use explicit names if you want to use a different name than the github user name:

.. code-block:: rst

    This change is due to :user:`Andreas Mueller <amueller>`.

Credits
*******

Credit goes to Jeff Forcier for his work on the `releases <https://github.com/bitprophet/releases>`_ extension, which is a full-featured solution for generating changelogs. I just needed a quick way to reference Github issues in my docs, so I yoinked the bits that I needed.

License
*******

MIT licensed. See the bundled `LICENSE <https://github.com/sloria/sphinx-issues/blob/master/LICENSE>`_ file for more details.


Changelog
*********

1.0.0 (2018-07-14)
------------------

- Add ``:pr:`` role. Thanks @jnotham for the suggestion.
- Drop support for Python 3.4.

0.4.0 (2017-11-25)
------------------

- Raise ``ValueError`` if neither ``issues_uri`` nor ``issues_github_path`` is set. Thanks @jnothman for the PR.
- Drop support for Python 2.6 and 3.3.

0.3.1 (2017-01-16)
------------------

- ``setup`` returns metadata, preventing warnings about parallel reads and writes. Thanks @jfinkels for reporting.

0.3.0 (2016-10-20)
------------------

- Support anchor text for ``:user:`` role. Thanks @jnothman for the suggestion and thanks @amueller for the PR.

0.2.0 (2014-12-22)
------------------

- Add ``:user:`` role for linking to Github user profiles.

0.1.0 (2014-12-21)
------------------

- Initial release.


