DOC Improve Contributer guide for writting docstrings (#31330)

ArturoAmorQ · ArturoAmorQ · StefanieSenger · web-flow · commit aca49c1dec16 · 2025-05-08T10:48:49.000Z
Co-authored-by: ArturoAmorQ &lt;arturo.amor-quiroz@polytechnique.edu&gt;
Co-authored-by: Stefanie Senger &lt;91849487+StefanieSenger@users.noreply.github.com&gt;
diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst
@@ -726,6 +726,19 @@ We are glad to accept any sort of documentation:
 
 .. dropdown:: Guidelines for writing docstrings
 
+  * You can use `pytest` to test docstrings, e.g. assuming the
+    `RandomForestClassifier` docstring has been modified, the following command
+    would test its docstring compliance:
+
+    .. prompt:: bash
+
+      pytest --doctest-modules sklearn/ensemble/_forest.py -k RandomForestClassifier
+
+  * The correct order of sections is: Parameters, Returns, See Also, Notes, Examples.
+    See the `numpydoc documentation
+    <https://numpydoc.readthedocs.io/en/latest/format.html#sections>`_ for
+    information on other possible sections.
+
   * When documenting the parameters and attributes, here is a list of some
     well-formatted examples
 
@@ -791,7 +804,15 @@ We are glad to accept any sort of documentation:
       SelectKBest : Select features based on the k highest scores.
       SelectFpr : Select features based on a false positive rate test.
 
-  * Add one or two snippets of code in "Example" section to show how it can be used.
+  * The "Notes" section is optional. It is meant to provide information on
+    specific behavior of a function/class/classmethod/method.
+
+  * A `Note` can also be added to an attribute, but in that case it requires
+    using the `.. rubric:: Note` directive.
+
+  * Add one or two **snippets** of code in "Example" section to show how it can
+    be used. The code should be runable as is, i.e. it should include all
+    required imports. Keep this section as brief as possible.
 
 
 .. dropdown:: Guidelines for writing the user guide and other reStructuredText documents
