Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

sphinx-issues

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

sphinx-issues

A Sphinx extension for linking to your project's issue tracker

  • 5.0.0
  • Source
  • PyPI
  • Socket score

Maintainers
1

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

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


5.0.0 (2024-10-11)

  • Remove :cwe: and :cve: roles, as these are officially included in Sphinx>=8.1.0.
  • Support Python 3.9-3.13. Python 3.8 is no longer supported.

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)

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.

Keywords

FAQs


Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc