From 60426a11d21fb1a2374b5035be8d3e716ed1a901 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 20 Mar 2024 12:31:32 -0400 Subject: [PATCH] Avoid over-linking --- documentation/markup.rst | 10 ++++++++++ documentation/style-guide.rst | 30 +++++++++++++++++++++++++++++- 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index dfabcd6668..32471b1d8c 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -30,11 +30,21 @@ external links ```Link text `_`` :ref:`hyperl roles w/ custom text ``:role:`custom text ``` :ref:`roles` roles w/ only last part ``:role:`~hidden.hidden.visible``` :ref:`roles` roles w/o link ``:role:`!target``` :ref:`roles` +roles w/o link, short ``:role:`!visible``` (Note 1) :ref:`roles` issues ``:gh:`ID```, ``:issue:`ID``` :ref:`roles` CPython source ``:source:`PATH``` :ref:`roles` comments ``.. a comment`` :ref:`comments` ======================= =========================================== ==================== +Notes: + +(1) + For an only-last-part reference with a suppressed link, + ``:role:`~!hidden.visible``` makes more semantic sense, but it causes + a warning as Sphinx tries to look up the reference ``!hidden.visible`` + which does not exist. The shorter form ``:role:`!visible`` renders as + desired and will build successfully. + .. _rst-primer: diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 0078d670e5..6b264fc478 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -124,11 +124,39 @@ explanation. provide context, make connections between topics, and discuss alternative opinions. There is no section dedicated to explanations but these can be found throughout Python's documentation, for example the - :ref:`python:unicode-howto` + :ref:`python:unicode-howto`. Please consult the `Diátaxis `_ guide for more detail. +Links +===== + +Linking words to more information about those words is a powerful tool for +helping people navigate documentation, but links can be over-used. +Links should be used only if they help the reader. + +Generally, a link should be provided for the first use of a term in a unit, +such as a section or paragraph. This is not a hard and fast rule. Sometimes +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. + +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 +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 +prefix: ``:func:`!map```. + Affirmative tone ================