DOC: Clarify the difference between document and section references

timhoffm · timhoffm · commit 58a35aa7d602 · 2023-07-29T00:44:16.000+02:00
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -194,9 +194,25 @@ nor the ````literal```` role:
 Refer 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 (associated  link to an anchor associated with a heading
+            with a section)
+==========  ===========================  ===========================================
+
+.. The following is a hack to have a link with literal formatting
+   See https://stackoverflow.com/a/4836544 and https://sphinx-doc.org/faq.html#reference-to-arbitrary-locations-in-external-documents
+
+.. |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
 
@@ -214,7 +230,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
