fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Tue, Jun 22, 2010 at 11:10:35PM +0200, Hans Petter Langtangen 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
>
> 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.

Why does it work for A and not for B? Does it only work once?

--
Anders

Attachment: signature.asc
Description: Digital signature