fenics team mailing list archive

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

On 22 June 2010 23:10, Hans Petter Langtangen <hpl@xxxxxxxxx> wrote:
> 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

The problem with this approach though is that we need to put the call
to the 'doc function' in the SWIG generated cpp.py module.
For the hand written modules in PyDOLFIN it is no problem to do this.

Kristian

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