diff --git a/CHANGES/13752.doc.rst b/CHANGES/13752.doc.rst new file mode 100644 index 00000000000..3b34b17d0e0 --- /dev/null +++ b/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`. diff --git a/docs/conf.py b/docs/conf.py index a3254645cfb..2c90f81ba32 100644 --- a/docs/conf.py +++ b/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 diff --git a/requirements/doc-spelling.txt b/requirements/doc-spelling.txt index bf90208b8f0..231a8a06876 100644 --- a/requirements/doc-spelling.txt +++ b/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 diff --git a/requirements/doc.in b/requirements/doc.in index 7106c3808d9..a353a6d9c38 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -1,6 +1,7 @@ aiohttp-theme myst-parser sphinx +sphinx-issues sphinxcontrib-mermaid sphinxcontrib-towncrier towncrier diff --git a/requirements/doc.txt b/requirements/doc.txt index ccf2b4197ae..07a50a4bb54 100644 --- a/requirements/doc.txt +++ b/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