From daa076f4ea131ad721685883c776033c90bcbf2a Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 7 Oct 2024 10:25:39 +0200 Subject: [PATCH] Make a dedicated section for cross-reference syntax in docs ... and rename the current "Cross-referencing syntax" page to "Cross-references", of which "Syntax" is one subsection. --- doc/index.rst | 2 +- doc/tutorial/narrative-documentation.rst | 2 +- doc/usage/referencing.rst | 13 +++++++++---- doc/usage/restructuredtext/roles.rst | 4 ++-- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index a46500771cc..f1cde1fd5fc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,7 +18,7 @@ Sphinx .. admonition:: 🔗 Powerful Cross-Referencing :class: sphinx-feature - Create :ref:`cross-references ` + Create :ref:`cross-references ` within your project, and even across :ref:`different projects `. Include references to diff --git a/doc/tutorial/narrative-documentation.rst b/doc/tutorial/narrative-documentation.rst index 0c413921909..38bac084c77 100644 --- a/doc/tutorial/narrative-documentation.rst +++ b/doc/tutorial/narrative-documentation.rst @@ -73,7 +73,7 @@ Adding cross-references ----------------------- One powerful feature of Sphinx is the ability to seamlessly add -:ref:`cross-references ` to specific parts of the documentation: +:ref:`cross-references ` to specific parts of the documentation: a document, a section, a figure, a code object, etc. This tutorial is full of them! diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 6c18cf80ea8..c13757e5c83 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -1,8 +1,8 @@ -.. _xref-syntax: +.. _xref: -======================== -Cross-referencing syntax -======================== +================ +Cross-references +================ One of Sphinx's most useful features is creating automatic cross-references through semantic cross-referencing roles. @@ -10,6 +10,11 @@ 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.). +.. _xref-syntax: + +Syntax +------ + Sphinx supports various cross-referencing roles to create links to other elements in the documentation. In general, writing ``:role:`target``` creates a link to diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index 4774b06195b..bf9f02945f5 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -18,8 +18,8 @@ They are written as ``:rolename:`content```. See :doc:`/usage/domains/index` for roles added by domains. -Cross-referencing syntax ------------------------- +Cross-references +---------------- See :doc:`/usage/referencing/`.