Improve the documentation style for human-readability in plain-text

1 files changed, 46 insertions, 51 deletions

diff --git a/numpy/doc/example.py b/numpy/doc/example.py
index 26d140e5f..0ae83d2bb 100644
--- a/numpy/doc/example.py
+++ b/numpy/doc/example.py
@@ -15,63 +15,58 @@ import numpy as np             # related third party imports next
 import scipy as sp             # imports should be at the top of the module
 import matplotlib as mpl       # imports should usually be on separate lines
 
-
-__docformat__ = "restructuredtext en"
-
-
 def foo(var1, var2, long_var_name='hi') :
     """One-line summary or signature.
 
     Several sentences providing an extended description. You can put
     text in mono-spaced type like so: ``var``.
 
-    *Parameters*:
-
-        var1 : {array_like}
-            Array_like means all those objects -- lists, nested lists, etc. --
-            that can be converted to an array.
-        var2 : {integer}
-            Write out the full type
-        long_variable_name : {'hi', 'ho'}, optional
-            Choices in brackets, default first when optional.
-
-    *Returns*:
-
-        named : {type}
-            Explanation
-        list
-            Explanation
-        of
-            Explanation
-        outputs
-            even more explaining
-
-    *Other Parameters*:
-
-        only_seldom_used_keywords : type
-            Explanation
-        common_parametrs_listed_above : type
-            Explanation
-
-    *See Also*:
-
-        `otherfunc` : relationship (optional)
-
-        `newfunc` : relationship (optional)
-
-    *Notes*
-
-        Notes about the implementation algorithm (if needed).
-
-        This can have multiple paragraphs as can all sections.
-
-    *Examples*
-
-        examples in doctest format
-
-        >>> a=[1,2,3]
-        >>> [x + 3 for x in a]
-        [4, 5, 6]
+    Parameters
+    ----------
+    var1 : array_like
+        Array_like means all those objects -- lists, nested lists, etc. --
+        that can be converted to an array.
+    var2 : integer
+        Write out the full type
+    long_variable_name : {'hi', 'ho'}, optional
+        Choices in brackets, default first when optional.
+
+    Returns
+    -------
+    named : type
+        Explanation
+    list
+        Explanation
+    of
+        Explanation
+    outputs
+        even more explaining
+
+    Other Parameters
+    ----------------
+    only_seldom_used_keywords : type
+        Explanation
+    common_parametrs_listed_above : type
+        Explanation
+
+    See Also
+    --------    
+    otherfunc : relationship (optional)
+    newfunc : relationship (optional)
+
+    Notes
+    -----
+    Notes about the implementation algorithm (if needed).
+
+    This can have multiple paragraphs as can all sections.
+
+    Examples
+    --------
+    examples in doctest format
+
+    >>> a=[1,2,3]
+    >>> [x + 3 for x in a]
+    [4, 5, 6]
 
     """