From a3ef76b113d205eb6e2425e1923e1a1f549c5752 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Wed, 2 Oct 2024 23:51:42 +0200 Subject: [PATCH 1/4] Improve cross-reference documentation Closes #12940. --- doc/usage/domains/python.rst | 38 +++++++++++++++++++++----- doc/usage/referencing.rst | 39 ++++++++++++++++----------- doc/usage/restructuredtext/basics.rst | 2 ++ 3 files changed, 57 insertions(+), 22 deletions(-) diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst index 5b98baa78b0..3f7bbe08007 100644 --- a/doc/usage/domains/python.rst +++ b/doc/usage/domains/python.rst @@ -716,15 +716,39 @@ a matching identifier is found: .. versionadded:: 0.4 -The name enclosed in this markup can include a module name and/or a class name. -For example, ``:py:func:`filter``` could refer to a function named ``filter`` -in the current module, or the built-in function of that name. In contrast, -``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the -``foo`` module. +Target specification +.................... -Normally, names in these roles are searched first without any further +The target can be specified as a fully qualified name, e.g. +``:py:meth:`mymodule.MyClass.my_method```, or any shortended version +(``:py:meth:`MyClass.my_method```, ``:py:meth:`my_method```). See +`python-target-resolution`_ for details on the resolution of shortend names. + +:ref:`Cross-referencing modifiers ` can be applied. In short: + +* You may supply an explicit title and reference target: ``:mod:`mathematical + functions ``` will refer to the ``math`` module, but the link text + will be "mathematical functions". + +* If you prefix the content with an exclamation mark ``!``, no reference/hyperlink + will be created. + +* If you prefix the content with ``~``, the link text will only be the last + component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. + +.. _python-target-resolution: + +Target resolution +................. + +A given link target name is resolved to an object using the following strategy: + +Names in these roles are searched first without any further qualification, then with the current module name prepended, then with the -current module and class name (if any) prepended. If you prefix the name with +current module and class name (if any) prepended. + +If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python's :mod:`codecs` module, ``:py:func:`open``` always refers to the built-in function, while ``:py:func:`.open``` refers to :func:`codecs.open`. diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 57611660f10..c6415d593c4 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -4,25 +4,32 @@ Cross-referencing syntax ======================== -Cross-references are generated by many semantic interpreted text roles. -Basically, you only need to write ``:role:`target```, and a link will be -created to the item named *target* of the type indicated by *role*. The link's -text will be the same as *target*. +Sphinx supports various cross-referencing roles to create links to other elements in +the documentation. Writing ``:role:`target``` creates a link to the item named +*target* of the type indicated by *role*. The link's text depends the role but is +often the same as or similar to *target*. -There are some additional facilities, however, that make cross-referencing -roles more versatile: +The behavior can be modified in the following ways: -* You may supply an explicit title and reference target, - like in reStructuredText direct hyperlinks: - ``:role:`title ``` will refer to *target*, - but the link text will be *title*. +* **Custom link text:** You can specify the link text explicitly using the same + notation as in reStructuredText :ref:`rst-external-links`: + ``:role:`link text ``` will refer to *target*, but the link text will be + *link text*. -* If you prefix the content with ``!``, no reference/hyperlink will be created. +* **Surpressed link:** Prefixing with an exclamation mark ``!``, prevents the + creation of a link but otherwise keeps the visual output of the role. Example: + ``:role:`!target```. -* If you prefix the content with ``~``, the link text will only be the last - component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will - refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This - does not work with all cross-reference roles, but is domain specific. + This is helpful for cases, in which the link target does not exist; e.g. + changelog entries that target removed functionality, or third-party libraries + without intersphinx. Surpressing the link prevents warnings in :confval:`nitpicky` + mode. + +* **Modified domain reference:** + When :ref:`referencing domain objects `, a tilde ``~`` prefix shortens + the link text the last component of the target. + For example, ``:py:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but + only display ``get`` as the link text. 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. @@ -71,6 +78,8 @@ Cross-referencing anything :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is found, all object types of intersphinx inventories are also searched. +.. _ref-objects: + Cross-referencing objects ------------------------- diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 53547486ac8..5d60ea81de4 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -203,6 +203,8 @@ Two more syntaxes are supported: *CSV tables* and *List tables*. They use an Hyperlinks ---------- +.. _rst-external-links: + External links ~~~~~~~~~~~~~~ From 131d1074c8c9293edf4585689f29a179dde47183 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Thu, 3 Oct 2024 00:00:15 +0200 Subject: [PATCH 2/4] Move any-role docs to the bottom of the page It's a rather niche application since specific roles are typically more concise, less error-prone and not more effort to type. --- doc/usage/referencing.rst | 88 ++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 43 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index c6415d593c4..2a288e5b0ca 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -35,49 +35,6 @@ The behavior can be modified in the following ways: tool-tip on mouse-hover) will always be the full target name. -.. _any-role: - -Cross-referencing anything --------------------------- - -.. rst:role:: any - - .. versionadded:: 1.3 - - This convenience role tries to do its best to find a valid target for its - reference text. - - * First, it tries standard cross-reference targets that would be referenced - by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. - - Custom objects added to the standard domain by extensions (see - :meth:`.Sphinx.add_object_type`) are also searched. - - * Then, it looks for objects (targets) in all loaded domains. It is up to - the domains how specific a match must be. For example, in the Python - domain a reference of ``:any:`Builder``` would match the - ``sphinx.builders.Builder`` class. - - If none or multiple targets are found, a warning will be emitted. In the - case of multiple targets, you can change "any" to a specific role. - - This role is a good candidate for setting :confval:`default_role`. If you - do, you can write cross-references without a lot of markup overhead. For - example, in this Python function documentation:: - - .. function:: install() - - This function installs a `handler` for every signal known by the - `signal` module. See the section `about-signals` for more information. - - there could be references to a glossary term (usually ``:term:`handler```), a - Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a - section (usually ``:ref:`about-signals```). - - The :rst:role:`any` role also works together with the - :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is - found, all object types of intersphinx inventories are also searched. - .. _ref-objects: Cross-referencing objects @@ -276,3 +233,48 @@ The following role creates a cross-reference to a term in a If you use a term that's not explained in a glossary, you'll get a warning during build. + + +.. _any-role: + +Cross-referencing anything +-------------------------- + +.. rst:role:: any + + .. versionadded:: 1.3 + + This convenience role tries to do its best to find a valid target for its + reference text. + + * First, it tries standard cross-reference targets that would be referenced + by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. + + Custom objects added to the standard domain by extensions (see + :meth:`.Sphinx.add_object_type`) are also searched. + + * Then, it looks for objects (targets) in all loaded domains. It is up to + the domains how specific a match must be. For example, in the Python + domain a reference of ``:any:`Builder``` would match the + ``sphinx.builders.Builder`` class. + + If none or multiple targets are found, a warning will be emitted. In the + case of multiple targets, you can change "any" to a specific role. + + This role is a good candidate for setting :confval:`default_role`. If you + do, you can write cross-references without a lot of markup overhead. For + example, in this Python function documentation:: + + .. function:: install() + + This function installs a `handler` for every signal known by the + `signal` module. See the section `about-signals` for more information. + + there could be references to a glossary term (usually ``:term:`handler```), a + Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a + section (usually ``:ref:`about-signals```). + + The :rst:role:`any` role also works together with the + :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is + found, all object types of intersphinx inventories are also searched. + From 3183bd56e3bece59f0140895d0949cc763e08b11 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 3 Oct 2024 15:55:14 +0100 Subject: [PATCH 3/4] Edits --- doc/usage/referencing.rst | 83 ++++++++++++++++++++++++++++----------- 1 file changed, 59 insertions(+), 24 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 2a288e5b0ca..02beaa6b80a 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -4,36 +4,71 @@ Cross-referencing syntax ======================== -Sphinx supports various cross-referencing roles to create links to other elements in -the documentation. Writing ``:role:`target``` creates a link to the item named -*target* of the type indicated by *role*. The link's text depends the role but is -often the same as or similar to *target*. +One of Sphinx's most useful features is creating automatic cross-references +through semantic cross-referencing roles. +A cross reference to an object description, such as ``:func:`spam```, +will create a link to the place where ``spam()`` is documented, +appropriate to each output format (HTML, PDF, ePUB, etc.). -The behavior can be modified in the following ways: +Sphinx supports various cross-referencing roles to create links +to other elements in the documentation. +In general, writing ``:role:`target``` creates a link to +the object called *target* of the type indicated by *role*. +The link's text depends the role but is often the same as or similar to *target*. -* **Custom link text:** You can specify the link text explicitly using the same - notation as in reStructuredText :ref:`rst-external-links`: - ``:role:`link text ``` will refer to *target*, but the link text will be - *link text*. +.. _xref-modifiers: -* **Surpressed link:** Prefixing with an exclamation mark ``!``, prevents the - creation of a link but otherwise keeps the visual output of the role. Example: - ``:role:`!target```. +The behavior can be modified in the following ways: - This is helpful for cases, in which the link target does not exist; e.g. - changelog entries that target removed functionality, or third-party libraries - without intersphinx. Surpressing the link prevents warnings in :confval:`nitpicky` - mode. +* **Custom link text:** + You can specify the link text explicitly using the same + notation as in reStructuredText :ref:`external links `: + ``:role:`custom text ``` will refer to *target* + and display *custom text* as the text of the link. -* **Modified domain reference:** - When :ref:`referencing domain objects `, a tilde ``~`` prefix shortens - the link text the last component of the target. - For example, ``:py:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but - only display ``get`` as the link text. +* **Suppressed link:** + Prefixing with an exclamation mark (``!``) prevents the creation of a link + but otherwise keeps the visual output of the role. - 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. + For example, writing ``:py:func:`!target``` displays :py:func:`!target`, + with no link generated. + This is helpful for cases in which the link target does not exist; + e.g. changelog entries that describe removed functionality, + or third-party libraries that don't support :doc:`intersphinx + `. + Suppressing the link prevents warnings in :confval:`nitpicky` mode. + +* **Modified domain reference:** + When :ref:`referencing domain objects `, + a tilde ``~`` prefix shortens the link text the last component of the target. + For example, ``:py:meth:`~queue.Queue.get``` will + refer to ``queue.Queue.get`` but only display ``get`` as the link text. + + 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. + +Some of the built-in cross-reference roles are: + +* :rst:role:`:any: `, + :rst:role:`:doc: `, + :rst:role:`:ref: ` +* :rst:role:`:confval: `, + :rst:role:`:envvar: `, + :rst:role:`:option: