fenics team mailing list archive

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

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).

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.

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-method-to-automatically-overwrite-that-of-another-me


Kristian