Skip to content

Avoid over-linking #1293 #1294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 27, 2024
Merged

Avoid over-linking #1293 #1294

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
60426a1
Avoid over-linking
nedbat Mar 20, 2024
02b0409
Update documentation/markup.rst
nedbat Mar 21, 2024
d8ab8d0
two updates from comments
nedbat Mar 21, 2024
834893f
update per ezio-melotti's comment
nedbat Mar 26, 2024
bc2b675
fix a sphinx lint failure
nedbat Mar 26, 2024
ec1f531
Update documentation/markup.rst
nedbat Mar 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions documentation/markup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,21 @@ external links ```Link text <https://example.com>`_`` :ref:`hyperl
roles w/ custom text ``:role:`custom text <target>``` :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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this should be included here. The quick reference lists commonly used markup, and what's being described here is not very common.

I would move this paragraph in the linked "roles" section, where the nuances of using ! and ~ are covered in more detail.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It took a few developers a while to work out what happened when trying to combine ~!, so I think it will be helpful to leave here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I'm thinking is:

  • the quick reference table is meant mostly for readers that already know about the existence and functioning of those constructs, but don't quite remember the syntax
  • all further details and explanations shouldn't (and aren't) covered here, but in the sections linked in the third column
  • if users look at the "roles" section (where ~ and ! are explained) for ways to combine ~/! they won't find it there, unless you duplicate the note there
  • the wording of roles w/o link, short is not too clear, since short doesn't mirror only last part (understandably, due to lack of space)
  • a reader might be wondering how to combine ~ and ! together, but :role:`!visible` doesn't seem an obvious answer to the question (unless they keep scrolling and read the note), especially since it doesn't have any apparent difference from :role:`!target`
  • the consequences of combining ~ and ! are a Sphinx implementation detail that shouldn't matter to the reader, so I would omit them from the note

My suggestion is to add:

* Combining ``~`` and ``!`` (e.g. ``:meth:`~!Queue.Queue.get```) is not supported.
  You can obtain the same result by simply using `!` and the last component of
  the target (e.g. ``:meth:`!get```).

in the "roles" section, after the bullet points that already explain ~ and ! and use Queue.Queue.get as an example.

The entry in the table could be removed altogether, since it's not a very common construct (trusting that the reader will follow the link looking for more information). If you prefer to keep it, the table should be updated by:

  • widening the first column and using roles w/o link, only last part to mirror the text of roles w/ only last part
  • reordering the entries so that roles w/o link comes first, roles w/ only last part next, and roles w/o link, only last part just after, so that the use of !visible is more evident.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nedbat Let me take some time to read @ezio-melotti's comment. Ezio makes some good points especially considering the original intent of the chart. There needs to be a new doc contributor cheat sheet (that is useful to current contributors) to guide folks on many of these markup constructs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ezio-melotti I like your suggestion, and have made it in the latest commit.



.. _rst-primer:

Expand Down
30 changes: 29 additions & 1 deletion documentation/style-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://diataxis.fr/>`_ guide for more
detail.

Links
=====

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
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```. See :ref:`roles` for more details.

Affirmative tone
================

Expand Down