DOC: Clarify the difference between document and section references

timhoffm · timhoffm · commit eeabdeed46e0 · 2023-07-28T08:55:08.000+02:00
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -194,9 +194,17 @@ 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:
+=========  ===========================  ===========================================
+Directive  Links target                 Representation in rendered HTML
+=========  ===========================  ===========================================
+``:doc:``  document                     link to a page
+``:ref:``  ReST label (associated with  link to an anchor associated with a heading
+           a section)
+=========  ===========================  ===========================================
+
+Examples:
 
 .. code-block:: rst
 
