fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Tue, Jun 22, 2010 at 02:33:32PM -0700, Johan Hake wrote:
> On Tuesday June 22 2010 14:30:23 Anders Logg wrote:
> > 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?
>
> A is an old style class and B is a new style class.

Ah, I didn't see that. Or rather I saw it but had forgotten about it
10 seconds later when I looked at the rest of the code... :-)

--
Anders

Attachment: signature.asc
Description: Digital signature