pep257 & numpydoc conforming docstrings

4 files changed, 156 insertions, 124 deletions

diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html
index 57a2cd3ef..3af79e8d6 100644
--- a/Doc/Manual/Python.html
+++ b/Doc/Manual/Python.html
@@ -5273,8 +5273,8 @@ def function_name(*args, **kwargs):
 
 <p>
 Level "2" results in the function prototype as per level "0". In addition, a line of
-documentation is generated for each parameter. Using the previous example, the generated
-code will be:
+documentation is generated for each parameter using <a href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpydoc</a> style.
+Using the previous example, the generated code will be:
 </p>
 
 <div class="targetlang">
@@ -5283,11 +5283,12 @@ def function_name(*args, **kwargs):
     """
     function_name(x, y, foo=None, bar=None) -&gt; bool
 
-    Parameters:
-        x: int
-        y: int
-        foo: Foo *
-        bar: Bar *
+    Parameters
+    ----------
+    x: int
+    y: int
+    foo: Foo *
+    bar: Bar *
 
     """
     ...
@@ -5318,11 +5319,12 @@ def function_name(*args, **kwargs):
   """
     function_name(x, y, foo=None, bar=None) -&gt; bool
 
-    Parameters:
-        x (C++ type: int) -- Input x dimension
-        y: int
-        foo: Foo *
-        bar: Bar *
+    Parameters
+    ----------
+    x (C++ type: int) -- Input x dimension
+    y: int
+    foo: Foo *
+    bar: Bar *
 
     """
 </pre>
@@ -5341,11 +5343,12 @@ def function_name(*args, **kwargs):
     """
     function_name(int x, int y, Foo foo=None, Bar bar=None) -&gt; bool
 
-    Parameters:
-        x: int
-        y: int
-        foo: Foo *
-        bar: Bar *
+    Parameters
+    ----------
+    x: int
+    y: int
+    foo: Foo *
+    bar: Bar *
 
     """
     ...
diff --git a/Examples/test-suite/autodoc.i b/Examples/test-suite/autodoc.i
index 07afa5794..eda04d293 100644
--- a/Examples/test-suite/autodoc.i
+++ b/Examples/test-suite/autodoc.i
@@ -1,4 +1,4 @@
-%module(docstring="hello") autodoc
+%module(docstring="hello.") autodoc
 
 %feature("autodoc");
 
@@ -27,7 +27,7 @@
 %feature("autodoc","2") A::variable_c; // extended
 %feature("autodoc","3") A::variable_d; // extended + types
 
-%feature("autodoc","just a string") A::funk; // names
+%feature("autodoc","just a string.") A::funk; // names
 
 %inline {
 
diff --git a/Examples/test-suite/python/autodoc_runme.py b/Examples/test-suite/python/autodoc_runme.py
index f5b6b7ce6..7256669d9 100644
--- a/Examples/test-suite/python/autodoc_runme.py
+++ b/Examples/test-suite/python/autodoc_runme.py
@@ -23,8 +23,8 @@ if not is_new_style_class(A):
 # skip builtin check - the autodoc is missing, but it probably should not be
 skip = True
 
-check(A.__doc__, "Proxy of C++ A class", "::A")
-check(A.funk.__doc__, "just a string")
+check(A.__doc__, "Proxy of C++ A class.", "::A")
+check(A.funk.__doc__, "just a string.")
 check(A.func0.__doc__,
       "func0(self, arg2, hello) -> int",
       "func0(arg2, hello) -> int")
@@ -35,17 +35,19 @@ check(A.func2.__doc__,
       "\n"
       "        func2(self, arg2, hello) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            arg2: short\n"
-      "            hello: int tuple[2]\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        arg2: short\n"
+      "        hello: int tuple[2]\n"
       "\n"
       "        ",
       "\n"
       "func2(arg2, hello) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    arg2: short\n"
-      "    hello: int tuple[2]\n"
+      "Parameters\n"
+      "----------\n"
+      "arg2: short\n"
+      "hello: int tuple[2]\n"
       "\n"
       ""
       )
@@ -53,17 +55,19 @@ check(A.func3.__doc__,
       "\n"
       "        func3(A self, short arg2, Tuple hello) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            arg2: short\n"
-      "            hello: int tuple[2]\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        arg2: short\n"
+      "        hello: int tuple[2]\n"
       "\n"
       "        ",
       "\n"
       "func3(short arg2, Tuple hello) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    arg2: short\n"
-      "    hello: int tuple[2]\n"
+      "Parameters\n"
+      "----------\n"
+      "arg2: short\n"
+      "hello: int tuple[2]\n"
       "\n"
       ""
       )
@@ -92,35 +96,39 @@ check(A.func2default.__doc__,
       "\n"
       "        func2default(self, e, arg3, hello, f=2) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg3: short\n"
-      "            hello: int tuple[2]\n"
-      "            f: double\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg3: short\n"
+      "        hello: int tuple[2]\n"
+      "        f: double\n"
       "\n"
       "        func2default(self, e, arg3, hello) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg3: short\n"
-      "            hello: int tuple[2]\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg3: short\n"
+      "        hello: int tuple[2]\n"
       "\n"
       "        ",
       "\n"
       "func2default(e, arg3, hello, f=2) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg3: short\n"
-      "    hello: int tuple[2]\n"
-      "    f: double\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg3: short\n"
+      "hello: int tuple[2]\n"
+      "f: double\n"
       "\n"
       "func2default(e, arg3, hello) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg3: short\n"
-      "    hello: int tuple[2]\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg3: short\n"
+      "hello: int tuple[2]\n"
       "\n"
       ""
       )
@@ -128,35 +136,39 @@ check(A.func3default.__doc__,
       "\n"
       "        func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg3: short\n"
-      "            hello: int tuple[2]\n"
-      "            f: double\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg3: short\n"
+      "        hello: int tuple[2]\n"
+      "        f: double\n"
       "\n"
       "        func3default(A self, A e, short arg3, Tuple hello) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg3: short\n"
-      "            hello: int tuple[2]\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg3: short\n"
+      "        hello: int tuple[2]\n"
       "\n"
       "        ",
       "\n"
       "func3default(A e, short arg3, Tuple hello, double f=2) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg3: short\n"
-      "    hello: int tuple[2]\n"
-      "    f: double\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg3: short\n"
+      "hello: int tuple[2]\n"
+      "f: double\n"
       "\n"
       "func3default(A e, short arg3, Tuple hello) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg3: short\n"
-      "    hello: int tuple[2]\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg3: short\n"
+      "hello: int tuple[2]\n"
       "\n"
       ""
       )
@@ -185,35 +197,39 @@ check(A.func2static.__doc__,
       "\n"
       "        func2static(e, arg2, hello, f=2) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg2: short\n"
-      "            hello: int tuple[2]\n"
-      "            f: double\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg2: short\n"
+      "        hello: int tuple[2]\n"
+      "        f: double\n"
       "\n"
       "        func2static(e, arg2, hello) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg2: short\n"
-      "            hello: int tuple[2]\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg2: short\n"
+      "        hello: int tuple[2]\n"
       "\n"
       "        ",
       "\n"
       "func2static(e, arg2, hello, f=2) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg2: short\n"
-      "    hello: int tuple[2]\n"
-      "    f: double\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg2: short\n"
+      "hello: int tuple[2]\n"
+      "f: double\n"
       "\n"
       "func2static(e, arg2, hello) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg2: short\n"
-      "    hello: int tuple[2]\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg2: short\n"
+      "hello: int tuple[2]\n"
       "\n"
       ""
       )
@@ -221,35 +237,39 @@ check(A.func3static.__doc__,
       "\n"
       "        func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg2: short\n"
-      "            hello: int tuple[2]\n"
-      "            f: double\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg2: short\n"
+      "        hello: int tuple[2]\n"
+      "        f: double\n"
       "\n"
       "        func3static(A e, short arg2, Tuple hello) -> int\n"
       "\n"
-      "        Parameters:\n"
-      "            e: A *\n"
-      "            arg2: short\n"
-      "            hello: int tuple[2]\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        e: A *\n"
+      "        arg2: short\n"
+      "        hello: int tuple[2]\n"
       "\n"
       "        ",
       "\n"
       "func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg2: short\n"
-      "    hello: int tuple[2]\n"
-      "    f: double\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg2: short\n"
+      "hello: int tuple[2]\n"
+      "f: double\n"
       "\n"
       "func3static(A e, short arg2, Tuple hello) -> int\n"
       "\n"
-      "Parameters:\n"
-      "    e: A *\n"
-      "    arg2: short\n"
-      "    hello: int tuple[2]\n"
+      "Parameters\n"
+      "----------\n"
+      "e: A *\n"
+      "arg2: short\n"
+      "hello: int tuple[2]\n"
       "\n"
       ""
       )
@@ -268,8 +288,9 @@ if sys.version_info[0:2] > (2, 4):
           "\n"
           "A_variable_c_get(self) -> int\n"
           "\n"
-          "Parameters:\n"
-          "    self: A *\n"
+          "Parameters\n"
+          "----------\n"
+          "self: A *\n"
           "\n",
           "A.variable_c"
           )
@@ -277,14 +298,15 @@ if sys.version_info[0:2] > (2, 4):
           "\n"
           "A_variable_d_get(A self) -> int\n"
           "\n"
-          "Parameters:\n"
-          "    self: A *\n"
+          "Parameters\n"
+          "----------\n"
+          "self: A *\n"
           "\n",
           "A.variable_d"
           )
 
 check(B.__doc__,
-      "Proxy of C++ B class",
+      "Proxy of C++ B class.",
       "::B"
       )
 check(C.__init__.__doc__, "__init__(self, a, b, h) -> C", None, skip)
@@ -294,10 +316,11 @@ check(E.__init__.__doc__,
       "\n"
       "        __init__(self, a, b, h) -> E\n"
       "\n"
-      "        Parameters:\n"
-      "            a: special comment for parameter a\n"
-      "            b: another special comment for parameter b\n"
-      "            h: enum Hola\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        a: special comment for parameter a\n"
+      "        b: another special comment for parameter b\n"
+      "        h: enum Hola\n"
       "\n"
       "        ", None, skip
       )
@@ -305,10 +328,11 @@ check(F.__init__.__doc__,
       "\n"
       "        __init__(F self, int a, int b, Hola h) -> F\n"
       "\n"
-      "        Parameters:\n"
-      "            a: special comment for parameter a\n"
-      "            b: another special comment for parameter b\n"
-      "            h: enum Hola\n"
+      "        Parameters\n"
+      "        ----------\n"
+      "        a: special comment for parameter a\n"
+      "        b: another special comment for parameter b\n"
+      "        h: enum Hola\n"
       "\n"
       "        ", None, skip
       )
diff --git a/Source/Modules/python.cxx b/Source/Modules/python.cxx
index 5670d9581..362a40929 100644
--- a/Source/Modules/python.cxx
+++ b/Source/Modules/python.cxx
@@ -799,7 +799,11 @@ public:
       Swig_register_filebyname("python", f_shadow);
 
       if (mod_docstring && Len(mod_docstring)) {
-	Printv(f_shadow, "\"\"\"\n", mod_docstring, "\n\"\"\"\n\n", NIL);
+        const char *triple_double = "\"\"\"";
+        // follow PEP257 rules: https://www.python.org/dev/peps/pep-0257/
+        // reported by pep257: https://github.com/GreenSteam/pep257
+        const bool multi_line_ds = Strchr(mod_docstring, '\n');
+        Printv(f_shadow, triple_double, multi_line_ds?"\n":"", mod_docstring, multi_line_ds?"\n":"", triple_double, "\n\n", NIL);
 	Delete(mod_docstring);
 	mod_docstring = NULL;
       }
@@ -1795,8 +1799,9 @@ public:
       Append(doc, name);
       if (pdoc) {
 	if (!pdocs)
-	  pdocs = NewString("\nParameters:\n");
-	Printf(pdocs, "    %s\n", pdoc);
+	  // numpydoc style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+	  pdocs = NewString("\nParameters\n----------\n");
+	Printf(pdocs, "%s\n", pdoc);
       }
       // Write the function annotation
       if (func_annotation)
@@ -1892,9 +1897,9 @@ public:
 		Delete(rname);
 	      } else {
 		if (CPlusPlus) {
-		  Printf(doc, "Proxy of C++ %s class", real_classname);
+		  Printf(doc, "Proxy of C++ %s class.", real_classname);
 		} else {
-		  Printf(doc, "Proxy of C %s struct", real_classname);
+		  Printf(doc, "Proxy of C %s struct.", real_classname);
 		}
 	      }
 	    }
@@ -4329,7 +4334,7 @@ public:
 	if (have_docstring(n)) {
 	  String *str = docstring(n, AUTODOC_CLASS, tab4);
 	  if (str && Len(str))
-	    Printv(f_shadow, tab4, str, "\n", NIL);
+	    Printv(f_shadow, tab4, str, "\n\n", NIL);
 	}
 
 	if (!modern) {