[DOC] move defaults in docs.py (#3621)

* update contributing

* multiline docstring

* update defaults

* flake8

* Apply suggestions from code review

* Update CONTRIBUTING.rst

Co-authored-by: bthirion <bertrand.thirion@inria.fr>

* Apply suggestions from code review

Co-authored-by: Yasmin <63292494+ymzayek@users.noreply.github.com>

* fix

* move default

* add defaults

* use single backtick

* use single backtick

* Update CONTRIBUTING.rst

Co-authored-by: bthirion <bertrand.thirion@inria.fr>

* sort alphabetically

* fix warnings

* reorder

* move default

* fix doc build

---------

Co-authored-by: bthirion <bertrand.thirion@inria.fr>
Co-authored-by: Yasmin <63292494+ymzayek@users.noreply.github.com>

CONTRIBUTING.rst

@@ -301,6 +301,44 @@ Each function and class must come with a “docstring” at the top of the funct
 using numpydoc_ formatting.
 The docstring must summarize what the function does and document every parameter.
 
+If an argument takes in a default value, it should be described
+with the type definition of that argument.
+
+See the examples below:
+
+.. code-block:: python
+
+      def good(x, y=1, z=None):
+      """Show how parameters are documented.
+
+      Parameters
+      ----------
+      x : :obj:`int`
+            X
+
+      y : :obj:`int`, default=1
+            Note that "default=1" is preferred to "Defaults to 1".
+
+      z : :obj:`str`, default=None
+
+      """
+
+      def bad(x, y=1, z=None):
+      """Show how parameters should not be documented.
+
+      Parameters
+      ----------
+      x :
+            The type of X is not described
+
+      y : :obj:`int`
+            The default value of y is not described.
+
+      z : :obj:`str`
+            Defaults=None.
+            The default value should be described after the type.
+      """
+
 Additionally, we consider it best practice to write modular functions;
 i.e., functions should preferably be relatively short and do *one* thing.
 This is also useful for writing unit tests.