Autolink GitHub issues

Automatically link plaintext issues, e.g. \#1, as #1.

This is a perfectly legitimately request, even sphinx’s own conf.py does a non-docutils hack to link plain-text nodes.

Configuration

In your conf.py:

1. Add 'linkify_issues' to extensions

   extensions = [
       # ...
       "linkify_issues",
   ]
   

2. Configure your issue URL, issue_url_tpl:

   # linkify_issues
   issue_url_tpl = 'https://github.com/git-pull/gp-libs/issues/{issue_id}'
   

   The config variable is formatted via str.format() where issue_id is 42 if the text is #42.

Issue pattern

issue_re is available to optionally adjust the pattern plain text is matched against. By default it is :var:linkify_issues

r"#(?P<issue_id>\d+)"

Where ^\ negates matches (as seen below) and numbers are matched via \d.

You can pass a str - which is automatically upcasted when parsing - or a :class:re.Pattern. In conf.py, to catch letters and dashes too:

issue_re = r"#(?P<issue_id>[\da-z-]+)"

That will match patterns like #ISSUE-34, where 'ISSUE-34' will be captured. What you may prefer is just capturing the 34:

issue_re = r"#ISSUE-(?P<issue_id>\d+)"

issue_url_tpl’s regex patterns can be extended and passed into issue_re’s string formatting:

issue_re = r"#(?P<page_type>(issue|pull)+)-(?P<issue_id>\d+)"
issue_url_tpl = "https://github.com/git-pull/gp-libs/{page_type}/{issue_id}"

#issue-1 will be #issue-1

#pull-1 will be #pull-1

If your needs are more complex, you may need to fork it for yourself or suggest a PR.

API

Autolinking extension for Sphinx.

linkify_issues.DEFAULT_ISSUE_RE = '#(?P<issue_id>\\d+)'

Default pattern to search plain nodes for issues.

class linkify_issues.LinkifyIssues(document, startnode=None)

Bases: SphinxTransform

Autolink references for Sphinx.

Initial setup for in-place document transforms.

default_priority = 999

Numerical priority of this transform, 0 through 999 (override).

apply()

Apply Sphinx transform.

Return type:

None

class linkify_issues.SetupDict

Bases: TypedDict

Setup mapping for Sphinx app.

version: str

parallel_read_safe: bool

parallel_write_safe: bool

linkify_issues.setup(app)

Initialize Sphinx extension for linkify_issues.

Return type:

SetupDict