[pull] master from aio-libs:master

CHANGES/13752.doc.rst

@@ -0,0 +1,6 @@
+Replaced most of the ``sphinx.ext.extlinks``-based roles in the documentation
+with :pypi:`sphinx-issues`, which ships the
+``:issue:``, ``:pr:``, ``:commit:`` and ``:user:`` roles out of the box.
+Pull request references are now captioned ``#N`` instead of ``PR #N``, and
+commit references as abbreviated, ``@``-prefixed hashes
+-- by :user:`aiolibsbot`.

docs/conf.py

@@ -62,6 +62,7 @@
     "myst_parser",  # renders Markdown sources (e.g. ``THREAT_MODEL.md``)
     "sphinxcontrib.mermaid",  # renders the Mermaid flowcharts in ``THREAT_MODEL.md``
     "sphinxcontrib.towncrier.ext",  # provides `towncrier-draft-entries` directive
+    "sphinx_issues",  # implements `:issue:`, `:pr:` and other GH-related roles
 ]
 
 
@@ -126,7 +127,6 @@
 github_repo_name = "aiohttp"
 github_repo_slug = f"{github_repo_org}/{github_repo_name}"
 github_repo_url = f"{github_url}/{github_repo_slug}"
-github_sponsors_url = f"{github_url}/sponsors"
 
 project = github_repo_name
 copyright = f"{project} contributors"
@@ -185,14 +185,24 @@
 # -- Extension configuration -------------------------------------------------
 
 # -- Options for extlinks extension ---------------------------------------
+# `:issue:`, `:pr:`, `:commit:` and `:user:` come from `sphinx-issues` below.
 extlinks = {
-    "issue": (f"{github_repo_url}/issues/%s", "#%s"),
-    "pr": (f"{github_repo_url}/pull/%s", "PR #%s"),
-    "commit": (f"{github_repo_url}/commit/%s", "%s"),
     "gh": (f"{github_url}/%s", "GitHub: %s"),
-    "user": (f"{github_sponsors_url}/%s", "@%s"),
 }
 
+# -- Options for sphinx_issues extension -------------------------------------
+
+# https://github.com/sloria/sphinx-issues#installation-and-configuration
+# The extension's default URL templates already match the ones the replaced
+# `extlinks` entries used -- including `:user:` pointing at GitHub Sponsors --
+# so only the repository slug needs to be configured.
+issues_github_path = github_repo_slug
+
+# The link captions differ slightly from the ones `extlinks` produced: `:pr:`
+# now renders as `#N` rather than `PR #N` and `:commit:` as an `@`-prefixed
+# abbreviated SHA. These are the extension's conventions and it only accepts
+# `#`, `@` or `!` as a prefix, so they are adopted as-is.
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

requirements/doc-spelling.txt

@@ -62,9 +62,12 @@ sphinx==8.1.3
     # via
     #   -r requirements/doc.in
     #   myst-parser
+    #   sphinx-issues
     #   sphinxcontrib-mermaid
     #   sphinxcontrib-spelling
     #   sphinxcontrib-towncrier
+sphinx-issues==6.0.0
+    # via -r requirements/doc.in
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0

requirements/doc.in

@@ -1,6 +1,7 @@
 aiohttp-theme
 myst-parser
 sphinx
+sphinx-issues
 sphinxcontrib-mermaid
 sphinxcontrib-towncrier
 towncrier

requirements/doc.txt

@@ -58,8 +58,11 @@ sphinx==8.1.3
     # via
     #   -r requirements/doc.in
     #   myst-parser
+    #   sphinx-issues
     #   sphinxcontrib-mermaid
     #   sphinxcontrib-towncrier
+sphinx-issues==6.0.0
+    # via -r requirements/doc.in
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0