[Numpy-discussion] f2py functions, docstrings, and epydoc

[Pearu Peterson]

Hi,

Tom Loredo wrote:
> Hi folks-
> 
> Can anyone offer any tips on how I can get epydoc to produce
> API documentation for functions in an f2py-produced module?
> Currently they get listed in the generated docs as "Variables":
> 
> Variables
>   	psigc = <fortran object at 0xa3e46b0>
>   	sigctp = <fortran object at 0xa3e4698>
>   	smll_offset = <fortran object at 0xa3e46c8>
> 
> Yet each of these objects is callable, and has a docstring.
> The module itself has docs that give a 1-line signature for
> each function, but that's only part of the docstring.

epydoc 3.0 supports variable documentation strings but only
in python codes. However, one can also let epydoc to generate
documentation for f2py generated functions (that, by the way, are
actually instances of `fortran` type and define __call__ method).
For that one needs to create a python module containing::

from somef2pyextmodule import psigc, sigctp, smll_offset

smll_offset = smll_offset
exec `smll_offset.__doc__`

sigctp = sigctp
exec `sigctp.__doc__`

smll_offset = smll_offset
exec `smll_offset.__doc__`

#etc

#eof

Now, when applying epydoc to this python file, epydoc will
produce docs also to these f2py objects.

It should be easy to create a python script that will
generate these python files that epydoc could use to
generate docs to f2py extension modules.

> One reason I'd like to see the full docstrings documented by epydoc
> is that, for key functions, I'm loading the functions into a
> module and *changing* the docstrings, to have info beyond the
> limited f2py-generated docstrings.
> 
> On a related question, is there a way to provide input to f2py for
> function docstrings?  The manual hints that triple-quoted multiline
> blocks in the .pyf can be used to provide documentation, but when
> I add them, they don't appear to be used.

This feature is still implemented only partially and not enabled.
When I get more time, I'll finish it..

HTH,
Pearu