From ddaef14181e68eee553f8edee1d6281ec08e71c4 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 8 Mar 2026 19:00:22 -0400 Subject: [PATCH 1/4] update the link guidance now that we suppress them automatically --- documentation/style-guide.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 4d2ca0d70..4291229b9 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -193,16 +193,18 @@ the second mention is more appropriate for a link. Some units are long enough to have a few repeated links. Use judgement to decide when a link will help the reader. -Do not use a link when the link would point to the current unit. It's natural -to use the name of a function in the documentation for the function, but a link -on that function name that simply reloads the section the user is already -reading is useless and distracting. +We use the `linklint Sphinx extension`__ to suppress two kinds of excessive +links: references in a section to itself and duplicate references in a +paragraph. Previously, editors had to carefully use an exclamation mark in a +Sphinx reference (``:func:`!map```) to prevent such links. + +__ https://pypi.org/project/linklint/ Do not use links in section headers. They distract from the title of the section. The term will be mentioned in the paragraph text and can be linked from there. -Sphinx provides ways to automatically add links to references, and a way to +Sphinx automatically adds links to references, and a way to suppress the link. Using roles like ``:func:`map``` will link to the documentation for ``map``. You can suppress the link while keeping the semantic presentation of the function name by adding an exclamation point From 9d351ac712f48a0d4e8a117db629490d345b46aa Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Mon, 9 Mar 2026 06:30:31 -0400 Subject: [PATCH 2/4] use linklint on the devguide (4 references unlinked) --- conf.py | 1 + requirements.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/conf.py b/conf.py index 0cb17ca74..1d8893722 100644 --- a/conf.py +++ b/conf.py @@ -3,6 +3,7 @@ from urllib.request import urlopen extensions = [ + 'linklint.ext', 'notfound.extension', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', diff --git a/requirements.txt b/requirements.txt index 7c2bbd806..3b40508f6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ furo>=2022.6.4 jinja2 +linklint sphinx-autobuild>=2024.9.19 sphinx-inline-tabs>=2023.4.21 sphinx-lint==1.0.2 From 31bf4b0d3fc6d4fdfb8ca39350f5d38f87d714f3 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 10 Mar 2026 07:46:15 -0400 Subject: [PATCH 3/4] Update documentation/style-guide.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 4291229b9..1a123480c 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -204,7 +204,7 @@ Do not use links in section headers. They distract from the title of the section. The term will be mentioned in the paragraph text and can be linked from there. -Sphinx automatically adds links to references, and a way to +Sphinx automatically adds links to references, and provides a way to suppress the link. Using roles like ``:func:`map``` will link to the documentation for ``map``. You can suppress the link while keeping the semantic presentation of the function name by adding an exclamation point From d5817ce9a364b440bb4b42ba218fc47877f84ab7 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 10 Mar 2026 07:50:23 -0400 Subject: [PATCH 4/4] updated per review feedback --- documentation/style-guide.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 1a123480c..5ca2960ce 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -193,12 +193,10 @@ the second mention is more appropriate for a link. Some units are long enough to have a few repeated links. Use judgement to decide when a link will help the reader. -We use the `linklint Sphinx extension`__ to suppress two kinds of excessive -links: references in a section to itself and duplicate references in a -paragraph. Previously, editors had to carefully use an exclamation mark in a -Sphinx reference (``:func:`!map```) to prevent such links. - -__ https://pypi.org/project/linklint/ +We use the :pypi:`linklint Sphinx extension ` to suppress two kinds +of excessive links: references in a section to itself and duplicate references +in a paragraph. Previously, editors had to carefully use an exclamation mark +in a Sphinx reference (``:func:`!map```) to prevent such links. Do not use links in section headers. They distract from the title of the section. The term will be mentioned in the paragraph text and can be linked @@ -206,7 +204,8 @@ from there. Sphinx automatically adds links to references, and provides a way to suppress the link. Using roles like ``:func:`map``` will link to the -documentation for ``map``. You can suppress the link while keeping the +documentation for ``map``. If automatic link suppression isn't enough, +you can suppress the link while keeping the semantic presentation of the function name by adding an exclamation point prefix: ``:func:`!map```. See :ref:`roles` for more details.