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.

Yes, I thought about using a simple nested dict, but then realised
that with a module I could test for missing documentation both ways
more easily.

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

I'll dig a bit into NumPy and see what I can find out. If it is easy
I'll prefer this approach since it looks cleaner than doing 1) and 2)
below.

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

We should do both 1) and 2) at the same time right?
It should definitely be possible to do 1), when building the
documentation, we can run a script that creates the docstrings.i file
which DOLFIN can simply copy.
The second part looks really good, I guess the docstrings module can
just be copied to DOLFIN on build too.

For both 1) and 2) we can still use the pseudo module, for 1) we just
need to have a manually updated list of classes/functions for which
the documentation should be written to docstings.i or is it possible
(perhaps better) to just dump all docstrings in docstrings.i and let
SWIG copy whatever it needs?

Kristian

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