From 707fde12e5ff2cac66942be1dad7cb591811ec88 Mon Sep 17 00:00:00 2001 From: hannah Date: Sat, 29 Jul 2023 21:40:07 -0400 Subject: [PATCH] Backport PR #26405: DOC: Clarify the difference between document and section references --- doc/devel/documenting_mpl.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index b814e67cd308..ad9ba885a3f4 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -187,9 +187,24 @@ nor the ````literal```` role: Referring to other documents and sections ----------------------------------------- -Sphinx_ allows internal references_ between documents. +Sphinx_ supports internal references_: -Documents can be linked with the ``:doc:`` directive: +========== =============== =========================================== +Role Links target Representation in rendered HTML +========== =============== =========================================== +|doc-dir|_ document link to a page +|ref-dir|_ reference label link to an anchor associated with a heading +========== =============== =========================================== + +.. The following is a hack to have a link with literal formatting + See https://stackoverflow.com/a/4836544 + +.. |doc-dir| replace:: ``:doc:`` +.. _doc-dir: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc +.. |ref-dir| replace:: ``:ref:`` +.. _ref-dir: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref + +Examples: .. code-block:: rst @@ -207,7 +222,7 @@ will render as: See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` -Sections can also be given reference names. For instance from the +Sections can also be given reference labels. For instance from the :doc:`/users/installing/index` link: .. code-block:: rst pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy