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
signature.asc
Description: Digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
