fenics team mailing list archive

[Kristian Oelgaard <k.b.oelgaard@xxxxxxxxx>]

On 22 June 2010 19:03, Johan Hake <johan.hake@xxxxxxxxx> wrote:
> On Tuesday June 22 2010 08:28:37 Kristian Oelgaard wrote:
>> I've started writing the programmer's reference for FEniCS.
>> One of the features that we decided on was that doc-strings for
>> PyDOLFIN should be written and maintained as part of the documentation
>> project and then added to the dolfin module on import.
>>
>> I thought about doing this in the following way:
>>
>> 1) Create a pseudo module 'dolfin-doc' which is a copy of the classes
>> and functions in the 'real' dolfin module only it contains no code at
>> all, just doc-strings. (This approach will also make it easy to create
>> a script to check if all functions are documented or if any docs are
>> obsolete).
>
> Sounds good. I first thought of a structure (other than a dummy class) that
> just mimics the class hierarchy, but in some way that is what you actually
> suggests and it is probably as easy as anything else.
>
>> 2) Use the autodoc functionality of Sphinx to create parts of the
>> documentation for functions and classes
>>
>> 3) Manually add additional information (in the reST file) and links to
>> other parts of the documentation like demos etc. This will not be
>> available using help() in the Python interpreter.
>>
>> 4) In the dolfin.__init__.py function import the 'dolfin-doc' module
>> and copy the doc-strings from all classes and functions to the classes
>> and functions in the real dolfin module as was suggested by Johan
>> Hake.
>>
>> The problem with this approach is that assigning to __doc__ is not
>> permitted for objects of 'type' type.
>
> :(
>
> I did not anticipate this. Not sure why this is. I have got the impression
> that numpy get around this. They use numpydoc to dynamically add their
> documentation. It makes heavy use of sphinx, but I couldn't figure how they
> get around that __doc__ is read-only.

To me it looks like numpydoc is a Sphinx extension that translates the
Numpy docstrings into something that Sphinx can understand, not the
other way around which is what we want.

http://projects.scipy.org/numpy/browser/trunk/doc/sphinxext/README.txt

So I think our best bet is to proceed with your suggestions below.

Kristian

> While it might be cool to look into what NumPy have done, (they also define a
> pseudo classes, which they populate with docstrings, (look into
> phantom_import.py), and they also define some nice format for the reST used in
> the docstrings), I suggest two things we can do:
>
> 1) SWIG can generate docstrings. We do that allready using parsed doxygen
> documentation. All of this is gathered in docstrings.i. I suggest generating
> such a file from our documentation. We need to turn of %feature("autodoc","1")
> in dolfin.i to get rid of the long and sometimes faulty generated signatures.
>
> 2) The added python classes and methods can be documented using your suggested
> approach, but instead of adding the docstring after class creation, do it
> during class (method or function) creation, a la:
>
>  class Foo(object):
>      __doc__ = docstrings.Foo.__doc__
>      ...
>
> where docstrings is the generated module containing the docstrings.
>
> Johan
>
>> In other words we can't assign to the __doc__ of
>>
>> class Foo(object):
>>     "Foo doc"
>>     pass
>>
>> Which is a new-style class and found in UFL and the SWIG code in DOLFIN.
>>
>> It works fine for
>>
>> def some_function(v):
>>     "function doc"
>>     return 2*v
>>
>> and
>>
>> class Bar:
>>     "Bar doc"
>>     pass
>>
>> which is the old-style class often found in FFC.
>>
>> Does anyone have a solution or comments to the above approach, or
>> maybe we can do it in a completely different way.
>>
>> I read about some workaround for the 'assign to __doc__' problem, but
>> it doesn't seem that nice and it might be a problem to incorporate in
>> the SWIG generated code?
>>
>> http://stackoverflow.com/questions/71817/using-the-docstring-from-one-metho
>> d-to-automatically-overwrite-that-of-another-me
>>
>>
>> Kristian
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>