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/documentation/style-guide.rst b/documentation/style-guide.rst index 4d2ca0d70..5ca2960ce 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -193,18 +193,19 @@ 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 :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 from there. -Sphinx provides ways to automatically add 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 +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. 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