fenics team mailing list archive

[Hans Petter Langtangen <hpl@xxxxxxxxx>]

Tue, 22 Jun 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).
> 
> 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 use to dynamically create a lot of doc strings. The thing is to
assign to __doc__ between the doc string and the methods in the class.
Here is a test case:

def generate():
    return ', with more text'

class A:
    'This is A'
    pass

class B(object):
    'This is B'
    __doc__ += generate()
    pass

A.__doc__ += generate()
print A.__doc__
print B.__doc__
B.__doc__ += generate()

unix> run tmp.py
This is A, with more text
This is B, with more text
Traceback (most recent call last):
  File "tmp.py", line 16, in <module>
    B.__doc__ += generate()
AttributeError: attribute '__doc__' of 'type' objects is not writable

The first assignment to __doc__ in class B went fine.

Hans Petter