DOC Add section to contributing.rst on cross referencing syntax (scikit-learn#24092)

lucyleeow · web-flow · commit 7781299cd229 · 2022-08-24T11:32:07.000+02:00
diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst
@@ -846,13 +846,67 @@ Finally, follow the formatting rules below to make it consistently good:
 * When editing reStructuredText (``.rst``) files, try to keep line length under
   80 characters when possible (exceptions include links and tables).
 
-* Do not modify sphinx labels as this would break existing cross references and
-  external links pointing to specific sections in the
-  scikit-learn documentation.
-
 * Before submitting your pull request check if your modifications have
   introduced new sphinx warnings and try to fix them.
 
+Cross-referencing
+-----------------
+
+It is often useful to cross-reference to other pages in the scikit-learn
+documentation. This should be done with reStructuredText cross-referencing
+syntax:
+
+* Section - to link to an arbitrary section in the documentation, use reference
+  labels (see
+  `Sphinx docs <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_).
+  For example:
+
+  .. code-block:: rst
+
+      .. _my-section:
+
+      My section
+      ----------
+
+      This is the text of the section.
+
+      To refer to itself use :ref:`my-section`.
+
+  You should not modify existing sphinx reference labels as this would break
+  existing cross references and external links pointing to specific sections in
+  the scikit-learn documentation.
+
+* Glossary - linking to a term in the :ref:`glossary`:
+
+  .. code-block:: rst
+
+      :term:`cross_validation`
+
+* Function - to link to the documentation of a function, use the full
+  import path to the function:
+
+  .. code-block:: rst
+
+      :func:`~sklearn.model_selection.cross_val_score`
+
+  However, if there is a 'currentmodule' directive above you in the document,
+  you will only need to use the path to the function succeeding the current
+  module specified. For example:
+
+  .. code-block:: rst
+
+      .. currentmodule:: sklearn.model_selection
+
+      :func:`cross_val_score`
+
+* Class - to link to documentation of a class, use the full import path to the
+  class, unless there is a 'currentmodule' directive in the document above
+  (see above):
+
+  .. code-block:: rst
+
+      :class:`~sklearn.preprocessing.StandardScaler`
+
 .. _generated_doc_CI:
 
 Generated documentation on GitHub Actions
