Skip to content

Backport PR #26405 on branch v3.7.2-doc (DOC: Clarify the difference between document and section references) #26413

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 1 commit into from
Jul 30, 2023
Merged

Backport PR #26405 on branch v3.7.2-doc (DOC: Clarify the difference between document and section references) #26413

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 18 additions & 3 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down