fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

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.

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