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
+33 −1
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
update per ezio-melotti's comment 
#1294 (comment)
  • Loading branch information
@nedbat
nedbat committed Mar 26, 2024
commit 834893fb6f434f46e36add3e6c38616a9eda9948
14 changes: 4 additions & 10 deletions documentation/markup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,21 +30,11 @@ 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.


.. _rst-primer:

Expand Down Expand Up @@ -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:

Expand Down
0