scikit-learn · lucyleeow · May 8, 2025 · May 7, 2025 · May 7, 2025 · May 7, 2025
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