sphinx-issues


Namesphinx-issues JSON
Version 0.4.0 PyPI version JSON
download
home_pagehttps://github.com/sloria/sphinx-issues
SummaryA Sphinx extension for linking to your project's issue tracker
upload_time2017-11-25 14:33:05
maintainer
docs_urlNone
authorSteven Loria
requires_python
licenseMIT
keywords sphinx issues github
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
coveralls test coverage No coveralls.
            =============
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 both issues and 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#changelog>`_, which makes use of the roles in this library.

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

    $ 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``.

.. 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}'

Usage
*****

Use the ``:issue:`` role in your docs like so:

.. code-block:: rst

    See issue :issue:`42`

    See issues :issue:`12,13`


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
*********

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

- Raise ``ValueError`` if neither ``issues_uri`` nor ``issues_github_path`` is set. Thanks @jnothman for the PR.

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.



            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "sphinx,issues,github", 
    "upload_time": "2017-11-25 14:33:05", 
    "author": "Steven Loria", 
    "home_page": "https://github.com/sloria/sphinx-issues", 
    "github_user": "sloria", 
    "download_url": "https://pypi.python.org/packages/a6/e0/c5f18ec00c12e3dda64b7862bddfa10be98d47f9546c7f47c865cb21d6b2/sphinx-issues-0.4.0.tar.gz", 
    "platform": "", 
    "version": "0.4.0", 
    "cheesecake_documentation_id": null, 
    "description": "=============\nsphinx-issues\n=============\n\n.. image:: https://travis-ci.org/sloria/sphinx-issues.svg?branch=master\n    :target: https://travis-ci.org/sloria/sphinx-issues\n\nA Sphinx extension for linking to your project's issue tracker. Includes roles for linking to both issues and user profiles, with built-in support for GitHub (though this works with other services).\n\nExample\n*******\n\nFor an example usage, check out `marshmallow's changelog <http://marshmallow.readthedocs.org/en/latest/changelog.html#changelog>`_, which makes use of the roles in this library.\n\nInstallation and Configuration\n******************************\n::\n\n    $ pip install sphinx-issues\n\nAdd ``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``.\n\n.. code-block:: python\n\n    # docs/conf.py\n\n    #...\n    extensions = [\n        #...\n        'sphinx_issues',\n    ]\n\n    # Github repo\n    issues_github_path = 'sloria/marshmallow'\n\n    # equivalent to\n    issues_uri = 'https://github.com/sloria/marshmallow/issues/{issue}'\n\nUsage\n*****\n\nUse the ``:issue:`` role in your docs like so:\n\n.. code-block:: rst\n\n    See issue :issue:`42`\n\n    See issues :issue:`12,13`\n\n\nUse 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).\n\n.. code-block:: rst\n\n    Thanks to :user:`bitprophet` for the idea!\n\nYou can also use explicit names if you want to use a different name than the github user name:\n\n.. code-block:: rst\n\n    This change is due to :user:`Andreas Mueller <amueller>`.\n\nCredits\n*******\n\nCredit 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.\n\nLicense\n*******\n\nMIT licensed. See the bundled `LICENSE <https://github.com/sloria/sphinx-issues/blob/master/LICENSE>`_ file for more details.\n\n\nChangelog\n*********\n\n0.4.0 (2017-11-25)\n------------------\n\n- Raise ``ValueError`` if neither ``issues_uri`` nor ``issues_github_path`` is set. Thanks @jnothman for the PR.\n\n0.3.1 (2017-01-16)\n------------------\n\n- ``setup`` returns metadata, preventing warnings about parallel reads and writes. Thanks @jfinkels for reporting.\n\n0.3.0 (2016-10-20)\n------------------\n\n- Support anchor text for ``:user:`` role. Thanks @jnothman for the suggestion and thanks @amueller for the PR.\n\n0.2.0 (2014-12-22)\n------------------\n\n- Add ``:user:`` role for linking to Github user profiles.\n\n0.1.0 (2014-12-21)\n------------------\n\n- Initial release.\n\n\n", 
    "tox": true, 
    "lcname": "sphinx-issues", 
    "bugtrack_url": null, 
    "github": true, 
    "coveralls": false, 
    "name": "sphinx-issues", 
    "license": "MIT", 
    "travis_ci": true, 
    "github_project": "sphinx-issues", 
    "summary": "A Sphinx extension for linking to your project's issue tracker", 
    "split_keywords": [
        "sphinx", 
        "issues", 
        "github"
    ], 
    "author_email": "sloria1@gmail.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2017-11-25T14:33:05", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/a6/e0/c5f18ec00c12e3dda64b7862bddfa10be98d47f9546c7f47c865cb21d6b2/sphinx-issues-0.4.0.tar.gz", 
            "md5_digest": "c9a9057be12dfc48507fbadc385dada2", 
            "downloads": 0, 
            "filename": "sphinx-issues-0.4.0.tar.gz", 
            "packagetype": "sdist", 
            "path": "a6/e0/c5f18ec00c12e3dda64b7862bddfa10be98d47f9546c7f47c865cb21d6b2/sphinx-issues-0.4.0.tar.gz", 
            "size": 4543
        }, 
        {
            "has_sig": false, 
            "upload_time": "2017-11-25T14:33:04", 
            "comment_text": "", 
            "python_version": "py2.py3", 
            "url": "https://pypi.python.org/packages/3a/60/dbe19e0e400ad5ea19d68a51127923f92759edd020f9ad22b68db29e52a1/sphinx_issues-0.4.0-py2.py3-none-any.whl", 
            "md5_digest": "06287296a7e6725aae3bd52e3f9b4fe4", 
            "downloads": 0, 
            "filename": "sphinx_issues-0.4.0-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "3a/60/dbe19e0e400ad5ea19d68a51127923f92759edd020f9ad22b68db29e52a1/sphinx_issues-0.4.0-py2.py3-none-any.whl", 
            "size": 5822
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}