Repository: scipy/scipy

Issue:
DOC: bad reST in scipy.optimize/_root.py
The docstring of ``_root_broyden1_doc`` or ``_root_broyden2_doc`` have wrong mark-up

https://github.com/scipy/scipy/blob/master/scipy/optimize/_root.py#L347-L357


According to [Docutils documentation](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists), lists must be separated by a blank line from contents before. As a result this is mis-interpreted as a [definition list](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists) as seen here https://docs.scipy.org/doc/scipy/reference/optimize.root-broyden1.html.


Discussion:

Resolving patch:
diff --git a/scipy/optimize/_root.py b/scipy/optimize/_root.py
--- a/scipy/optimize/_root.py
+++ b/scipy/optimize/_root.py
@@ -345,16 +345,23 @@ def _root_broyden1_doc():
                 method and values for additional parameters.
 
                 Methods available:
-                    - ``restart``: drop all matrix columns. Has no
+
+                    - ``restart``
+                        Drop all matrix columns. Has no
                         extra parameters.
-                    - ``simple``: drop oldest matrix column. Has no
+                    - ``simple``
+                        Drop oldest matrix column. Has no
                         extra parameters.
-                    - ``svd``: keep only the most significant SVD
+                    - ``svd``
+                        Keep only the most significant SVD
                         components.
-                      Extra parameters:
-                          - ``to_retain``: number of SVD components to
-                              retain when rank reduction is done.
-                              Default is ``max_rank - 2``.
+
+                        Extra parameters:
+
+                            - ``to_retain``
+                                Number of SVD components to
+                                retain when rank reduction is done.
+                                Default is ``max_rank - 2``.
             max_rank : int, optional
                 Maximum rank for the Broyden matrix.
                 Default is infinity (ie., no rank reduction).
@@ -403,16 +410,23 @@ def _root_broyden2_doc():
             method and values for additional parameters.
 
             Methods available:
-                - ``restart``: drop all matrix columns. Has no
+
+                - ``restart``
+                    Drop all matrix columns. Has no
                     extra parameters.
-                - ``simple``: drop oldest matrix column. Has no
+                - ``simple``
+                    Drop oldest matrix column. Has no
                     extra parameters.
-                - ``svd``: keep only the most significant SVD
+                - ``svd``
+                    Keep only the most significant SVD
                     components.
-                  Extra parameters:
-                      - ``to_retain``: number of SVD components to
-                          retain when rank reduction is done.
-                          Default is ``max_rank - 2``.
+
+                    Extra parameters:
+                  
+                        - ``to_retain``
+                            Number of SVD components to
+                            retain when rank reduction is done.
+                            Default is ``max_rank - 2``.
         max_rank : int, optional
             Maximum rank for the Broyden matrix.
             Default is infinity (ie., no rank reduction).


Test patch: