ENH: f2py: generate docstrings in Numpy docstring format

5 files changed, 53 insertions, 22 deletions

diff --git a/numpy/f2py/capi_maps.py b/numpy/f2py/capi_maps.py
index 7fd1179c3..dd8277aaf 100644
--- a/numpy/f2py/capi_maps.py
+++ b/numpy/f2py/capi_maps.py
@@ -367,26 +367,26 @@ def getpydocsign(a,var):
 
     if hasinitvalue(var):
         init,showinit=getinit(a,var)
-        init='= %s'%(showinit)
+        init = ', optional\\n    Default: %s' % showinit
     if isscalar(var):
         if isintent_inout(var):
-            sig='%s :%s %s rank-0 array(%s,\'%s\')'%(a,init,opt,c2py_map[ctype],
-                              c2pycode_map[ctype],)
+            sig='%s : %s rank-0 array(%s,\'%s\')%s'%(a,opt,c2py_map[ctype],
+                              c2pycode_map[ctype], init)
         else:
-            sig='%s :%s %s %s'%(a,init,opt,c2py_map[ctype])
+            sig='%s : %s %s%s'%(a,opt,c2py_map[ctype],init)
         sigout='%s : %s'%(out_a,c2py_map[ctype])
     elif isstring(var):
         if isintent_inout(var):
-            sig='%s :%s %s rank-0 array(string(len=%s),\'c\')'%(a,init,opt,getstrlength(var))
+            sig='%s : %s rank-0 array(string(len=%s),\'c\')%s'%(a,opt,getstrlength(var),init)
         else:
-            sig='%s :%s %s string(len=%s)'%(a,init,opt,getstrlength(var))
+            sig='%s : %s string(len=%s)%s'%(a,opt,getstrlength(var),init)
         sigout='%s : string(len=%s)'%(out_a,getstrlength(var))
     elif isarray(var):
         dim=var['dimension']
         rank=`len(dim)`
-        sig='%s :%s %s rank-%s array(\'%s\') with bounds (%s)'%(a,init,opt,rank,
+        sig='%s : %s rank-%s array(\'%s\') with bounds (%s)%s'%(a,opt,rank,
                                              c2pycode_map[ctype],
-                                             ','.join(dim))
+                                             ','.join(dim), init)
         if a==out_a:
             sigout='%s : rank-%s array(\'%s\') with bounds (%s)'\
                     %(a,rank,c2pycode_map[ctype],','.join(dim))
diff --git a/numpy/f2py/rules.py b/numpy/f2py/rules.py
index 9d943e884..86dcaa8a1 100644
--- a/numpy/f2py/rules.py
+++ b/numpy/f2py/rules.py
@@ -259,7 +259,7 @@ routine_rules={
     'separatorsfor':sepdict,
     'body':"""
 #begintitle#
-static char doc_#apiname#[] = \"\\\nFunction signature:\\n\\\n\t#docreturn##name#(#docsignatureshort#)\\n\\\n#docstrsigns#\";
+static char doc_#apiname#[] = \"\\\n#docreturn##name#(#docsignatureshort#)\\\n\\\n\\n#docstrsigns#\";
 /* #declfortranroutine# */
 static PyObject *#apiname#(const PyObject *capi_self,
                            PyObject *capi_args,
@@ -351,10 +351,10 @@ rout_rules=[
     'freemem':'/*freemem*/',
     'docsignshort':'','docsignoptshort':'',
     'docstrsigns':'','latexdocstrsigns':'',
-    'docstrreq':'Required arguments:',
-    'docstropt':'Optional arguments:',
-    'docstrout':'Return objects:',
-    'docstrcbs':'Call-back functions:',
+    'docstrreq':'\\nParameters\\n----------',
+    'docstropt':'\\nOther Parameters\\n----------------',
+    'docstrout':'\\nReturns\\n-------',
+    'docstrcbs':'\\nNotes\\n-----\\nCall-back functions::\\n',
     'latexdocstrreq':'\\noindent Required arguments:',
     'latexdocstropt':'\\noindent Optional arguments:',
     'latexdocstrout':'\\noindent Return objects:',
@@ -482,7 +482,7 @@ rout_rules=[
     },{ # Function
     'functype':'#ctype#',
     'docreturn':{l_not(isintent_hide):'#rname#,'},
-    'docstrout':'\t#pydocsignout#',
+    'docstrout':'#pydocsignout#',
     'latexdocstrout':['\\item[]{{}\\verb@#pydocsignout#@{}}',
                       {hasresultnote:'--- #resultnote#'}],
     'callfortranroutine':[{l_and(debugcapi,isstringfunction):"""\
@@ -618,7 +618,7 @@ aux_rules=[
     },
     {
     'return':',#varname#',
-    'docstrout':'\t#pydocsignout#',
+    'docstrout':'#pydocsignout#',
     'docreturn':'#outvarname#,',
     'returnformat':'#varrformat#',
     '_check':l_and(isscalar,l_not(iscomplex),isintent_out),
@@ -698,9 +698,9 @@ arg_rules=[
     },
 # Doc signatures
     {
-    'docstropt':{l_and(isoptional,isintent_nothide):'\t#pydocsign#'},
-    'docstrreq':{l_and(isrequired,isintent_nothide):'\t#pydocsign#'},
-    'docstrout':{isintent_out:'\t#pydocsignout#'},
+    'docstropt':{l_and(isoptional,isintent_nothide):'#pydocsign#'},
+    'docstrreq':{l_and(isrequired,isintent_nothide):'#pydocsign#'},
+    'docstrout':{isintent_out:'#pydocsignout#'},
     'latexdocstropt':{l_and(isoptional,isintent_nothide):['\\item[]{{}\\verb@#pydocsign#@{}}',
                                                           {hasnote:'--- #note#'}]},
     'latexdocstrreq':{l_and(isrequired,isintent_nothide):['\\item[]{{}\\verb@#pydocsign#@{}}',
@@ -732,7 +732,7 @@ arg_rules=[
     { # Common
     'docsignxa':{isintent_nothide:'#varname#_extra_args=(),'},
     'docsignxashort':{isintent_nothide:'#varname#_extra_args,'},
-    'docstropt':{isintent_nothide:'\t#varname#_extra_args := () input tuple'},
+    'docstropt':{isintent_nothide:'#varname#_extra_args : input tuple, optional\\n    Default: ()'},
     'docstrcbs':'#cbdocstr#',
     'latexdocstrcbs':'\\item[] #cblatexdocstr#',
     'latexdocstropt':{isintent_nothide:'\\item[]{{}\\verb@#varname#_extra_args := () input tuple@{}} --- Extra arguments for call-back function {{}\\verb@#varname#@{}}.'},
@@ -990,7 +990,7 @@ if (#varname#_capi==Py_None) {
     'keys_xa':',&capi_overwrite_#varname#',
     'docsignxa':'overwrite_#varname#=1,',
     'docsignxashort':'overwrite_#varname#,',
-    'docstropt':'\toverwrite_#varname# := 1 input int',
+    'docstropt':'overwrite_#varname# : input int, optional\\n    Default: 1',
     '_check':l_and(isarray,isintent_overwrite),
     },{
     'frompyobj':'\tcapi_#varname#_intent |= (capi_overwrite_#varname#?0:F2PY_INTENT_COPY);',
@@ -1004,7 +1004,7 @@ if (#varname#_capi==Py_None) {
      'keys_xa':',&capi_overwrite_#varname#',
      'docsignxa':'overwrite_#varname#=0,',
      'docsignxashort':'overwrite_#varname#,',
-     'docstropt':'\toverwrite_#varname# := 0 input int',
+     'docstropt':'overwrite_#varname# : input int, optional\\n    Default: 0',
      '_check':l_and(isarray,isintent_copy),
      },{
      'frompyobj':'\tcapi_#varname#_intent |= (capi_overwrite_#varname#?0:F2PY_INTENT_COPY);',
@@ -1322,6 +1322,7 @@ def buildmodule(m,um):
 ################## Build C/API function #############
 
 stnd={1:'st',2:'nd',3:'rd',4:'th',5:'th',6:'th',7:'th',8:'th',9:'th',0:'th'}
+
 def buildapi(rout):
     rout,wrap = func2subr.assubr(rout)
     args,depargs=getargs2(rout)
diff --git a/numpy/f2py/src/fortranobject.c b/numpy/f2py/src/fortranobject.c
index f5e2c6244..c07de99c0 100644
--- a/numpy/f2py/src/fortranobject.c
+++ b/numpy/f2py/src/fortranobject.c
@@ -126,9 +126,9 @@ fortran_doc (FortranDataDef def) {
         size += strlen(def.doc);
     p = (char*)malloc (size);
     p[0] = '\0'; /* make sure that the buffer has zero length */
-    if (sprintf(p,"%s - ",def.name)==0) goto fail;
     if (def.rank==-1) {
         if (def.doc==NULL) {
+            if (sprintf(p,"%s - ",def.name)==0) goto fail;
             if (sprintf(p+strlen(p),"no docs available")==0)
                 goto fail;
         } else {
diff --git a/numpy/f2py/tests/test_callback.py b/numpy/f2py/tests/test_callback.py
index 6a201a951..3ed6d1da5 100644
--- a/numpy/f2py/tests/test_callback.py
+++ b/numpy/f2py/tests/test_callback.py
@@ -38,6 +38,31 @@ cf2py  intent(out) a
         for name in "t,t2".split(","):
             self.check_function(name)
 
+    @dec.slow
+    def test_docstring(self):
+        assert_equal(self.module.t.__doc__,
+                     "a = t(fun,[fun_extra_args])\n"
+                     "\n"
+                     "Parameters\n"
+                     "----------\n"
+                     "fun : call-back function\n"
+                     "\n"
+                     "Other Parameters\n"
+                     "----------------\n"
+                     "fun_extra_args : input tuple, optional\n"
+                     "    Default: ()\n"
+                     "\n"
+                     "Returns\n-------\n"
+                     "a : int\n"
+                     "\n"
+                     "Notes\n"
+                     "-----\n"
+                     "Call-back functions::\n"
+                     "\n"
+                     "  def fun(): return a\n"
+                     "  Return objects:\n"
+                     "    a : int\n")
+
     def check_function(self, name):
         t = getattr(self.module, name)
         r = t(lambda : 4)
diff --git a/numpy/f2py/tests/test_mixed.py b/numpy/f2py/tests/test_mixed.py
index a8a14ca4b..70a1d7c66 100644
--- a/numpy/f2py/tests/test_mixed.py
+++ b/numpy/f2py/tests/test_mixed.py
@@ -20,6 +20,11 @@ class TestMixed(util.F2PyTest):
         assert_( self.module.foo_fixed.bar12() == 12)
         assert_( self.module.foo_free.bar13() == 13)
 
+    @dec.slow
+    def test_docstring(self):
+        assert_equal(self.module.bar11.__doc__,
+                     "a = bar11()\n\nReturns\n-------\na : int\n")
+
 if __name__ == "__main__":
     import nose
     nose.runmodule()