| Name | sphinx-issues JSON |
| Version |
4.1.0
JSON |
| download |
| home_page | None |
| Summary | A Sphinx extension for linking to your project's issue tracker |
| upload_time | 2024-04-15 03:04:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
sphinx
issues
github
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
=============
sphinx-issues
=============
.. image:: https://badgen.net/pypi/v/sphinx-issues
:target: https://pypi.org/project/sphinx-issues/
:alt: PyPI badge
.. image:: https://github.com/sloria/sphinx-issues/actions/workflows/build-release.yml/badge.svg
:target: https://github.com/sloria/sphinx-issues/actions/workflows/build-release.yml
:alt: Build status
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``.
The extension has default values for GitHub projects.
Simply set the add the ``issues_default_group_project`` config variable and you are good
to go:
.. code-block:: python
# docs/conf.py
# ...
extensions = [
# ...
"sphinx_issues"
]
# Path to GitHub repo {group}/{project} (note that `group` is the GitHub user or organization)
issues_github_path = "sloria/marshmallow"
# which is the equivalent to:
issues_uri = "https://github.com/{group}/{project}/issues/{issue}"
issues_prefix = "#"
issues_pr_uri = "https://github.com/{group}/{project}/pull/{pr}"
issues_pr_prefix = "#"
issues_commit_uri = "https://github.com/{group}/{project}/commit/{commit}"
issues_commit_prefix = "@"
issues_user_uri = "https://github.com/{user}"
issues_user_prefix = "@"
The extension is very configurable and can be used with any kind of
issue tracker. Here is how you could configure it for use
with a custom hosed GitLab instance:
.. code-block:: python
# docs/conf.py
# ...
extensions = [
# ...
"sphinx_issues"
]
# Default repo {group}/{project} of gitlab project
issues_default_group_project = "myteam/super_great_project"
issues_uri = "https://gitlab.company.com/{group}/{project}/-/issues/{issue}"
issues_prefix = "#"
issues_pr_uri = "https://gitlab.company.com/{group}/{project}/-/merge_requests/{pr}"
issues_pr_prefix = "!"
issues_commit_uri = "https://gitlab.company.com/{group}/{project}/-/commit/{commit}"
issues_commit_prefix = "@"
issues_user_uri = "https://gitlab.company.com/{user}"
issues_user_prefix = "@"
Usage inside the documentation
******************************
Use the ``:issue:`` and ``:pr:`` roles in your docs like so:
.. code-block:: rst
See issue :issue:`42`
See issues :issue:`12,13`
See :issue:`sloria/konch#45`.
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).
Use the ``:commit:`` role to link to commits.
.. code-block:: rst
Fixed in :commit:`6bb9124d5e9dbb2f7b52864c3d8af7feb1b69403`.
Use the ``:cve:`` role to link to CVEs on https://cve.mitre.org.
.. code-block:: rst
:cve:`CVE-2018-17175` - Addresses possible vulnerability when...
.. 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>`.
The syntax ``:role:`My custom title <target>``` works for all roles of this extension.
It can be also used in combination with a list:
.. code-block:: rst
Fix bad bug :issue:`123, (Duplicate) <199>`
Use the ``:cwe:`` role to link to CWEs on https://cwe.mitre.org.
.. code-block:: rst
:cwe:`CWE-787` - The software writes data past the end, or...
Use the ``:pypi:`` role to link to PyPI on https://pypi.org.
.. code-block:: rst
:pypi:`sphinx-issues` - A Sphinx extension for linking to your project's issue tracker.
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
*********
4.1.0 (2024-04-14)
------------------
- Add `:pypi:` role for linking to PyPI projects (`#144 <https://github.com/sloria/sphinx-issues/issues/144>`_).
Thanks @shenxianpeng for the suggestion and PR.
4.0.0 (2024-01-19)
------------------
- Default to linking GH Sponsors for the :user: role (`#129 <https://github.com/sloria/sphinx-issues/issues/129>`_).
Thanks @webknjaz for the suggestion.
- Support Python 3.8-3.12. Older versions are no longer supported.
- *Backwards-incompatible*: Remove ``__version__``, ``__author__``, and ``__license__`` attributes.
Use ``importlib.metadata`` to read this metadata instead.
3.0.1 (2022-01-11)
------------------
- Fix regression from 3.0.0: `exception: 'in <string>' requires string as left operand, not type`.
3.0.0 (2022-01-10)
------------------
- The `:commit:` role now outputs with an `@` prefix.
- Add configuration options for changing prefixes.
- Allow `{group}` to be specified within `issues_uri`, `issues_pr_uri`, `issues_commit_uri`, and
2.0.0 (2022-01-01)
------------------
- Drop support for Python 2.7 and 3.5.
- Test against Python 3.8 to 3.10.
- Add ``:cwe:`` role for linking to CVEs on https://cwe.mitre.org.
Thanks @hugovk for the PR.
- Add support for custom urls and separators `Issue #93 <https://github.com/sloria/sphinx-issues/issues/93>`_
- Allow custom titles for all roles `Issue #116 <https://github.com/sloria/sphinx-issues/issues/116>`_
- Added setting `issues_default_group_project` as future replacement of `issues_github_path`, to reflect the now to universal nature of the extension
1.2.0 (2018-12-26)
------------------
- Add ``:commit:`` role for linking to commits.
- Add support for linking to external repos.
- Test against Python 3.7.
1.1.0 (2018-09-18)
------------------
- Add ``:cve:`` role for linking to CVEs on https://cve.mitre.org.
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-issues",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sphinx, issues, github",
"author": null,
"author_email": "Steven Loria <sloria1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ba/fb/fa7829987e801056f16d8c63ace3f1d6f91e44940ad00f512450581ed63f/sphinx_issues-4.1.0.tar.gz",
"platform": null,
"description": "=============\nsphinx-issues\n=============\n\n.. image:: https://badgen.net/pypi/v/sphinx-issues\n :target: https://pypi.org/project/sphinx-issues/\n :alt: PyPI badge\n\n.. image:: https://github.com/sloria/sphinx-issues/actions/workflows/build-release.yml/badge.svg\n :target: https://github.com/sloria/sphinx-issues/actions/workflows/build-release.yml\n :alt: Build status\n\nA 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).\n\nExample\n*******\n\nFor 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.\n\nInstallation and Configuration\n******************************\n\n.. code-block:: console\n\n pip install sphinx-issues\n\n\nAdd ``sphinx_issues`` to ``extensions`` in your ``conf.py``.\n\nThe extension has default values for GitHub projects.\nSimply set the add the ``issues_default_group_project`` config variable and you are good\nto go:\n\n.. code-block:: python\n\n # docs/conf.py\n\n # ...\n extensions = [\n # ...\n \"sphinx_issues\"\n ]\n\n # Path to GitHub repo {group}/{project} (note that `group` is the GitHub user or organization)\n issues_github_path = \"sloria/marshmallow\"\n\n # which is the equivalent to:\n issues_uri = \"https://github.com/{group}/{project}/issues/{issue}\"\n issues_prefix = \"#\"\n issues_pr_uri = \"https://github.com/{group}/{project}/pull/{pr}\"\n issues_pr_prefix = \"#\"\n issues_commit_uri = \"https://github.com/{group}/{project}/commit/{commit}\"\n issues_commit_prefix = \"@\"\n issues_user_uri = \"https://github.com/{user}\"\n issues_user_prefix = \"@\"\n\nThe extension is very configurable and can be used with any kind of\nissue tracker. Here is how you could configure it for use\nwith a custom hosed GitLab instance:\n\n.. code-block:: python\n\n # docs/conf.py\n\n # ...\n extensions = [\n # ...\n \"sphinx_issues\"\n ]\n\n # Default repo {group}/{project} of gitlab project\n issues_default_group_project = \"myteam/super_great_project\"\n issues_uri = \"https://gitlab.company.com/{group}/{project}/-/issues/{issue}\"\n issues_prefix = \"#\"\n issues_pr_uri = \"https://gitlab.company.com/{group}/{project}/-/merge_requests/{pr}\"\n issues_pr_prefix = \"!\"\n issues_commit_uri = \"https://gitlab.company.com/{group}/{project}/-/commit/{commit}\"\n issues_commit_prefix = \"@\"\n issues_user_uri = \"https://gitlab.company.com/{user}\"\n issues_user_prefix = \"@\"\n\n\nUsage inside the documentation\n******************************\n\nUse the ``:issue:`` and ``:pr:`` roles 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 See :issue:`sloria/konch#45`.\n\n See PR :pr:`58`\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\nUse the ``:commit:`` role to link to commits.\n\n.. code-block:: rst\n\n Fixed in :commit:`6bb9124d5e9dbb2f7b52864c3d8af7feb1b69403`.\n\nUse the ``:cve:`` role to link to CVEs on https://cve.mitre.org.\n\n.. code-block:: rst\n\n :cve:`CVE-2018-17175` - Addresses possible vulnerability when...\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\nThe syntax ``:role:`My custom title <target>``` works for all roles of this extension.\n\nIt can be also used in combination with a list:\n\n.. code-block:: rst\n\n Fix bad bug :issue:`123, (Duplicate) <199>`\n\nUse the ``:cwe:`` role to link to CWEs on https://cwe.mitre.org.\n\n.. code-block:: rst\n\n :cwe:`CWE-787` - The software writes data past the end, or...\n\nUse the ``:pypi:`` role to link to PyPI on https://pypi.org.\n\n.. code-block:: rst\n\n :pypi:`sphinx-issues` - A Sphinx extension for linking to your project's issue tracker.\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\n4.1.0 (2024-04-14)\n------------------\n\n- Add `:pypi:` role for linking to PyPI projects (`#144 <https://github.com/sloria/sphinx-issues/issues/144>`_).\n Thanks @shenxianpeng for the suggestion and PR.\n\n4.0.0 (2024-01-19)\n------------------\n\n- Default to linking GH Sponsors for the :user: role (`#129 <https://github.com/sloria/sphinx-issues/issues/129>`_).\n Thanks @webknjaz for the suggestion.\n- Support Python 3.8-3.12. Older versions are no longer supported.\n- *Backwards-incompatible*: Remove ``__version__``, ``__author__``, and ``__license__`` attributes.\n Use ``importlib.metadata`` to read this metadata instead.\n\n3.0.1 (2022-01-11)\n------------------\n\n- Fix regression from 3.0.0: `exception: 'in <string>' requires string as left operand, not type`.\n\n3.0.0 (2022-01-10)\n------------------\n\n- The `:commit:` role now outputs with an `@` prefix.\n- Add configuration options for changing prefixes.\n- Allow `{group}` to be specified within `issues_uri`, `issues_pr_uri`, `issues_commit_uri`, and \n\n2.0.0 (2022-01-01)\n------------------\n\n- Drop support for Python 2.7 and 3.5.\n- Test against Python 3.8 to 3.10.\n- Add ``:cwe:`` role for linking to CVEs on https://cwe.mitre.org.\n Thanks @hugovk for the PR.\n- Add support for custom urls and separators `Issue #93 <https://github.com/sloria/sphinx-issues/issues/93>`_\n- Allow custom titles for all roles `Issue #116 <https://github.com/sloria/sphinx-issues/issues/116>`_\n- Added setting `issues_default_group_project` as future replacement of `issues_github_path`, to reflect the now to universal nature of the extension\n\n1.2.0 (2018-12-26)\n------------------\n\n- Add ``:commit:`` role for linking to commits.\n- Add support for linking to external repos.\n- Test against Python 3.7.\n\n1.1.0 (2018-09-18)\n------------------\n\n- Add ``:cve:`` role for linking to CVEs on https://cve.mitre.org.\n\n1.0.0 (2018-07-14)\n------------------\n\n- Add ``:pr:`` role. Thanks @jnotham for the suggestion.\n- Drop support for Python 3.4.\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- Drop support for Python 2.6 and 3.3.\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",
"bugtrack_url": null,
"license": null,
"summary": "A Sphinx extension for linking to your project's issue tracker",
"version": "4.1.0",
"project_urls": {
"Issues": "https://github.com/sloria/sphinx-issues/issues",
"Source": "https://github.com/sloria/sphinx-issues"
},
"split_keywords": [
"sphinx",
" issues",
" github"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d07c0a7c1a38392f2922b4b693dd8acd6a4c7e662ee66db058bdf314bd22ce3f",
"md5": "2960831eab2c4627b25b51a4134ff0cc",
"sha256": "d779dddff441175c9fddb7a4018eca38f9f6cdb1e0a2fe31d93b4f89587c7ba1"
},
"downloads": -1,
"filename": "sphinx_issues-4.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2960831eab2c4627b25b51a4134ff0cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8248,
"upload_time": "2024-04-15T03:04:37",
"upload_time_iso_8601": "2024-04-15T03:04:37.610042Z",
"url": "https://files.pythonhosted.org/packages/d0/7c/0a7c1a38392f2922b4b693dd8acd6a4c7e662ee66db058bdf314bd22ce3f/sphinx_issues-4.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bafbfa7829987e801056f16d8c63ace3f1d6f91e44940ad00f512450581ed63f",
"md5": "32aa8ad8672baa29fd81c73d8d65a8e3",
"sha256": "a67f7ef31d164b420b2f21b6c9b020baeb4a014afd4045f5be314c984e8ee520"
},
"downloads": -1,
"filename": "sphinx_issues-4.1.0.tar.gz",
"has_sig": false,
"md5_digest": "32aa8ad8672baa29fd81c73d8d65a8e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14148,
"upload_time": "2024-04-15T03:04:39",
"upload_time_iso_8601": "2024-04-15T03:04:39.382108Z",
"url": "https://files.pythonhosted.org/packages/ba/fb/fa7829987e801056f16d8c63ace3f1d6f91e44940ad00f512450581ed63f/sphinx_issues-4.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-15 03:04:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sloria",
"github_project": "sphinx-issues",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx-issues"
}
