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. You can assign to B's __doc__ as many times as you want as long as you do it within the class definition. Johan > -- > Anders _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
