Re: [Numpy-discussion] f2py functions, docstrings, and epydoc
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 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] f2py functions, docstrings, and epydoc
Pearu- smll_offset = smll_offset exec `smll_offset.__doc__` Thanks for the quick and helpful response! I'll give it a try. I don't grasp why it works, though. I suppose I don't need to, but... I'm guessing the exec adds stuff to the current namespace that isn't there until a fortran object's attributes are explicitly accessed. While I have your attention... could you clear this up, also just for my curiousity? It's probably related. f2py generated functions (that, by the way, are actually instances of `fortran` type and define __call__ method). I had wondered about this when I first encountered this issue, and thought maybe I could figure out how to put some hook into epydoc so it would document anything with a __call__ method. But it looks like 'fortran' objects *don't* have a __call__ (here _cbmlike is my f2py-generated module): In [1]: from inference.count._cbmlike import smllike In [2]: smllike Out[2]: fortran object at 0x947a668 In [3]: dir smllike -- dir(smllike) Out[3]: ['__doc__', '_cpointer'] In [4]: smllike.__call__ --- AttributeErrorTraceback (most recent call last) /home/inference/loredo/tex/meetings/head08/ipython console in module() AttributeError: __call__ Yet despite this apparent absence of __call__, I can magically call smllike just fine. Would you provide a quick explanation of what f2py and the fortran object are doing here? Thanks, Tom - This mail sent through IMP: http://horde.org/imp/ ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] f2py functions, docstrings, and epydoc
On Thu, March 27, 2008 7:20 pm, Tom Loredo wrote: Pearu- smll_offset = smll_offset exec `smll_offset.__doc__` Thanks for the quick and helpful response! I'll give it a try. I don't grasp why it works, though. I suppose I don't need to, but... I'm guessing the exec adds stuff to the current namespace that isn't there until a fortran object's attributes are explicitly accessed. While I have your attention... could you clear this up, also just for my curiousity? It's probably related. I got this idea from how epydoc gets documentation strings for variables: http://epydoc.sourceforge.net/whatsnew.html according to the variable assignement must follow a string constant containing documentation. In our case, smll_offset = smll_offset is variable assignment and exec `smll_offset.__doc__` creates a string constant after the variable assingment. f2py generated functions (that, by the way, are actually instances of `fortran` type and define __call__ method). I had wondered about this when I first encountered this issue, and thought maybe I could figure out how to put some hook into epydoc so it would document anything with a __call__ method. But it looks like 'fortran' objects *don't* have a __call__ (here _cbmlike is my f2py-generated module): In [1]: from inference.count._cbmlike import smllike In [2]: smllike Out[2]: fortran object at 0x947a668 In [3]: dir smllike -- dir(smllike) Out[3]: ['__doc__', '_cpointer'] In [4]: smllike.__call__ --- AttributeErrorTraceback (most recent call last) /home/inference/loredo/tex/meetings/head08/ipython console in module() AttributeError: __call__ Yet despite this apparent absence of __call__, I can magically call smllike just fine. Would you provide a quick explanation of what f2py and the fortran object are doing here? `fortran` object is an instance of a *extension type* `fortran`. It does not have __call__ method, the extension type has a slot in C struct that holds a function that will be called when something tries to call the `fortran` object. If there are epydoc developers around in this list then here's a feature request: epydoc support for extension types. Regards, Pearu ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] f2py functions, docstrings, and epydoc
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. 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. Thanks, Tom - This mail sent through IMP: http://horde.org/imp/ ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
