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:

Add 'linkify_issues' to extensions

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

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.

linkify_issues.DEFAULT_ISSUE_RE = '#(?P<issue_id>\\d+)'#: Default pattern to search plain nodes for issues.

class linkify_issues.LinkifyIssues(document, startnode=None)[source]#

Initial setup for in-place document transforms.

default_priority = 999#: Numerical priority of this transform, 0 through 999 (override).

Override to apply the transform to the document tree.

class linkify_issues.SetupDict[source]#

Bases: TypedDict

linkify_issues.setup(app)[source]#