8000 Avoid over-linking #1293 by nedbat · Pull Request #1294 · python/devguide · GitHub
[go: up one dir, main page]
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

Changes from 1 commit
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
Prev Previous commit
Next Next commit
two updates from comments
  • Loading branch information
@nedbat
nedbat committed Mar 21, 2024
commit d8ab8d0164b3046736bd92548f7e0ec36df1a12b
8 changes: 4 additions & 4 deletions documentation/style-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
================
Expand Down
0