How to document fortran function for f2py?

Question

I would like to use docstring or something similar to document my fortran routines which can be usable with the python help command. The autogenerated docstring made by f2py is very not sufficient and I need to add more details in the same way we do with the python function docstring.

In my idea, it should look like :

mymod.f :

subroutine foo()
! This is my function
end subroutine

and in a python session:

>>> import mymod
>>> help(mymod.foo)

Answer 1

A somewhat dirty solution is to save the documentation in ascii files and load them at run time. The f2py doc is hard coded at compile time and an option to modify it in the wrapper is not available so far I think (this would be nice!).

You can for example write an __init__.py file that loads the f2py compiled module _mymodule.so and overwrites or appends to the f2py __doc__ strings. ">> mymodule.function?" in ipython works then but surprisingly ">> help(mymodule.function)" doesn't! (no idea why...)

The following snippet of an __init__.py takes documentation that is stored in folder doc/ and files doc/"function name".doc that are associated to each function. In this case the documentation is always loaded but you could also load it manually.

def load_documentation():
    """
    Fills the modules __doc__ strings
    """

    import os
    from . import _mymodule
    print('loading documentation')
    docfolder = os.path.abspath(os.path.join(os.path.dirname(__file__), 'doc'))
    for name,func in _mymodule.__dict__.items():
        if callable(func):
            try:
                path = os.path.join(docfolder,name.lower()+'.doc')

                docfile = open(path)
                doc = docfile.read()
                docfile.close()

                func.__doc__ = doc 
            except IOError as msg:
                print(msg)

load_documentation()

from _mymodule import *