From 60426a11d21fb1a2374b5035be8d3e716ed1a901 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 20 Mar 2024 12:31:32 -0400 Subject: [PATCH 1/6] 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 ================ From 02b04092ca3fb19f70cd2fe528f3c17b5c34eab1 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Thu, 21 Mar 2024 08:12:54 -0400 Subject: [PATCH 2/6] Update documentation/markup.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Éric --- documentation/markup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 32471b1d8c..cf331cb9cc 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -40,7 +40,7 @@ Notes: (1) For an only-last-part reference with a suppressed link, - ``:role:`~!hidden.visible``` makes more semantic sense, but it causes + ``:role:`~!hidden.visible``` makes more 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. From d8ab8d0164b3046736bd92548f7e0ec36df1a12b Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Thu, 21 Mar 2024 08:18:14 -0400 Subject: [PATCH 3/6] two updates from comments --- documentation/style-guide.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 6b264fc478..6fea1712b2 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -132,9 +132,9 @@ 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. +Links are a powerful tool for helping people navigate documentation and find +more information, 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 @@ -155,7 +155,7 @@ 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```. +prefix: ``:func:`!map```. See :ref:`roles` for more details. Affirmative tone ================ From 834893fb6f434f46e36add3e6c38616a9eda9948 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 26 Mar 2024 15:45:47 -0600 Subject: [PATCH 4/6] update per ezio-melotti's comment https://github.com/python/devguide/pull/1294#discussion_r1535088844 --- documentation/markup.rst | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index cf331cb9cc..2f008e842d 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -30,21 +30,11 @@ 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 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: @@ -763,6 +753,10 @@ versatile: In HTML output, the link's ``title`` attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name. +* Combining ``~`` and ``!`` (for example, ``:meth:`~!Queue.Queue.get```) is not + supported. You can obtain the same result by simply using `!` and the last + component of the target (for example, ``:meth:`!get```). + The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found: From bc2b675ed0413921361d256ae0154a6aeeb20815 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 26 Mar 2024 15:49:57 -0600 Subject: [PATCH 5/6] fix a sphinx lint failure --- documentation/markup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 2f008e842d..580410bc98 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -754,7 +754,7 @@ versatile: tool-tip on mouse-hover) will always be the full target name. * Combining ``~`` and ``!`` (for example, ``:meth:`~!Queue.Queue.get```) is not - supported. You can obtain the same result by simply using `!` and the last + supported. You can obtain the same result by simply using ``!`` and the last component of the target (for example, ``:meth:`!get```). The following roles refer to objects in modules and are possibly hyperlinked if From ec1f531dd7de1b385400801728d5bed88fa4cff5 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 27 Mar 2024 08:50:32 -0400 Subject: [PATCH 6/6] Update documentation/markup.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- documentation/markup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 580410bc98..830493a31c 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -754,7 +754,7 @@ versatile: tool-tip on mouse-hover) will always be the full target name. * Combining ``~`` and ``!`` (for example, ``:meth:`~!Queue.Queue.get```) is not - supported. You can obtain the same result by simply using ``!`` and the last + supported. You can obtain the same result by using ``!`` and the last component of the target (for example, ``:meth:`!get```). The following roles refer to objects in modules and are possibly hyperlinked if