{"id":9318,"library":"sphinx-issues","title":"Sphinx Issues","description":"Sphinx Issues is a Sphinx extension designed to facilitate linking to a project's issue tracker directly within reStructuredText documentation. It provides roles for creating links to issues, pull requests, user profiles, and commits, with built-in support for GitHub and flexible configuration for other platforms like GitLab. The current version is 6.0.0, released on March 13, 2026, and it maintains an active development and release cadence.","status":"active","version":"6.0.0","language":"en","source_language":"en","source_url":"https://github.com/sloria/sphinx-issues","tags":["sphinx","documentation","issues","github","gitlab","extension","restructuredtext"],"install":[{"cmd":"pip install sphinx-issues","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generator framework. sphinx-issues v6.0.0 requires Sphinx >= 8.1.0.","package":"Sphinx","optional":false},{"reason":"Runtime environment. Requires Python >=3.10 (3.10-3.14 supported for v6.0.0).","package":"Python","optional":false}],"imports":[{"note":"sphinx-issues is enabled as a Sphinx extension by adding its module name to the 'extensions' list in your project's conf.py file.","symbol":"sphinx_issues","correct":"extensions = ['sphinx_issues']"}],"quickstart":{"code":"# conf.py\n\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1'\n\nextensions = [\n    'sphinx_issues'\n]\n\n# Required for GitHub integration\n# Replace 'sloria/marshmallow' with your project's GitHub path (user/repo or org/repo)\nissues_github_path = 'sloria/marshmallow'\n\n# Example usage in an .rst file:\n# See issue :issue:`42`\n# See PR :pr:`58`\n# Thanks to :user:`bitprophet`\n# Fixed in :commit:`6bb9124d5e9dbb2f7b52864c3d8af7feb1b69403`\n","lang":"python","description":"To quickly integrate `sphinx-issues`, first install it via pip. Then, add `'sphinx_issues'` to the `extensions` list in your Sphinx project's `conf.py`. For GitHub projects, configure `issues_github_path` to specify your repository. This enables the `:issue:`, `:pr:`, `:commit:`, and `:user:` roles in your reStructuredText files."},"warnings":[{"fix":"In `conf.py`, set `issues_github_path = 'your_github_user_or_org/your_repo_name'` for GitHub, or explicitly define `issues_uri`, `issues_pr_uri`, `issues_commit_uri`, and `issues_user_uri` for other services.","message":"Version 6.0.0 removes implicit extraction of the group/project from GitHub URLs when `issues_uri` is set. You must now explicitly define `issues_github_path` or `issues_default_group_project` for GitHub projects, or fully specify `issues_uri` and related paths for custom trackers.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade Sphinx to version 8.1 or higher. If upgrading Sphinx is not an option, downgrade `sphinx-issues` to `<5.0.0`.","message":"As of version 5.0.0, the `:cwe:` and `:cve:` roles were removed from `sphinx-issues` because these roles are now officially included in Sphinx >= 8.1. If you are using Sphinx < 8.1 and still require these roles, you must pin `sphinx-issues` to a version less than 5 (`sphinx-issues<5`).","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Python environment to 3.10 or newer. If you must use Python 3.9 or older, you will need to use an older version of `sphinx-issues` (e.g., `<6.0.0`).","message":"sphinx-issues v6.0.0 officially supports Python 3.10-3.14. Python 3.9 and older versions are no longer supported. Ensure your project's Python environment meets this requirement to avoid installation or runtime issues.","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Ensure your Sphinx installation is `sphinx>=8.1.0`. Update Sphinx using `pip install -U sphinx` or specify the version in your `requirements.txt`.","message":"`sphinx-issues` version 6.0.0 requires Sphinx version 8.1.0 or newer. Installing `sphinx-issues` v6.0.0 with an older Sphinx version may lead to unexpected behavior or build errors.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that `sphinx_issues` is included in the `extensions` list within your `conf.py` file: `extensions = ['sphinx_issues', ...]`. Ensure `sphinx-issues` is installed in your environment.","cause":"The `sphinx_issues` extension has not been correctly added to the `extensions` list in `conf.py`, or Sphinx cannot find the `sphinx_issues` module.","error":"Unknown interpreted text role 'issue'"},{"fix":"Add `issues_github_path = 'YOUR_GITHUB_USER_OR_ORG/YOUR_REPO_NAME'` to your `conf.py`. For other issue trackers, explicitly define `issues_uri` and related `issues_pr_uri`, etc.","cause":"For GitHub projects, the `issues_github_path` variable is missing or incorrectly configured in `conf.py` after upgrading to `sphinx-issues` 6.0.0.","error":"Sphinx build warning: Issues configuration (issues_github_path or issues_default_group_project) not found. Issue/PR roles may not generate correct URLs."},{"fix":"Use `importlib.metadata.version('sphinx-issues')` to programmatically retrieve the installed version, and similarly for other metadata.","cause":"Attempting to access `__version__`, `__author__`, or `__license__` directly from the `sphinx_issues` module after upgrading to version 6.0.0. These attributes were removed in this version.","error":"AttributeError: module 'sphinx_issues' has no attribute '__version__'"}]}