fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

[snip]

> > 
> > This has been the procedure for now. It is probably possible to change
> > this workflow, to a more automatic one.
> 
> Would it be possible to integrate it in the build system? Or too much
> noise every time we build?

I think it takes too much time now. It is especially the doxygen part of the 
docstring generation that takes time. This will of course change when we 
integrate the new documentation efforts.

> It should at least be integrated in the release script. I have added
> it to the pre-release hook of the release script now. We might want to
> have a top-level script that does all the import/autogeneration magic
> Kristian is working on, including calling generate.py in dolfin/swig.
> Look at the file release.conf.

This is probably better than nothing, but DOLFIN should be ready for release 
when this script is run. If the script has not been called before release has 
been decided it might produce a different release which need to be tested, at 
least the PyDOLFIN part. 

Johan

> 
> --
> Anders
> 
> > Johan
> > 
> > > >> 2) Extend our Python layer with all functions and classes that we
> > > >> want to use the dolfindoc docstrings for.
> > > >> These should just be empty and redirect calls to classes and
> > > >> functions of the cpp. In dolfin/mesh/mesh.py:
> > > >> 
> > > >> class Mesh(cpp.Mesh):
> > > >>     def size(self):
> > > >>         try:
> > > >>             import dolfindoc.mesh.mesh
> > > >>             __doc__ = dolfindoc.mesh.mesh.Mesh.__doc__
> > > >>         
> > > >>         except:
> > > >>             __doc__ = cpp.Mesh.__doc__
> > > >>         
> > > >>         return cpp.Mesh.size()
> > > >> 
> > > >> An additional benefit of this approach is that the module structure
> > > >> can be identical to what we have in the _real_ DOLFIN, not as it is
> > > >> now where everything is dumped in the dolfin.cpp module.
> > > >> I don't know how much overhead this will create, alternatively we
> > > >> can skip the try/except clause and simply have the documentation as
> > > >> a dependency, or not add the docstrings for memberfunctions and add
> > > >> them later on import as was the original idea.
> > > > 
> > > > This sounds cumbersome and in the example above will the try: except
> > > > clause be called everytime size is called.
> > > 
> > > Yes, I thought about having no docstrings as default (just need them
> > > for the class docstring) and the dynamically add them on import for
> > > all member functions.
> > > I know it's a bit more work, but we will have the same layout of
> > > modules as we have for the directories in DOLFIN.
> > > 
> > > Kristian
> > > 
> > > > Johan
> > > > 
> > > >> Suggestions and comments are more than welcome!
> > > >> 
> > > >> Kristian
> > > >> 
> > > >> > then in dolfin/__init__.py we load the classes as we do now from
> > > >> > the dolfin module, and then iterate over all functions and member
> > > >> > functions and substitute docstrings from the dolfindoc module.
> > > >> > 
> > > >> > Kristian
> > > >> > 
> > > >> >>> 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.
> > > >> >>> 
> > > >> >>> 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-fr
> > > >> >>>> om-o ne- 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
> > > >> 
> > > >> _______________________________________________
> > > >> Mailing list: https://launchpad.net/~fenics
> > > >> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> > > >> Unsubscribe : https://launchpad.net/~fenics
> > > >> More help   : https://help.launchpad.net/ListHelp
> > 
> > _______________________________________________
> > Mailing list: https://launchpad.net/~fenics
> > Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~fenics
> > More help   : https://help.launchpad.net/ListHelp