fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Friday September 3 2010 01:20:16 Kristian Ølgaard wrote:
> On 3 September 2010 08:45, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
> > On 03/09/10 00:48, Johan Hake wrote:
> >> Hello!
> >> 
> >> I wonder how the docstring module is generated. More presisly the cpp.py
> >> file in that module. It looks very similare to what was generated by the
> >> generate_docstring.py which is still provided in DOLFIN.
> 
> The idea with the current setup is to write all docstrings in the
> site-packages/dolfin/docstrings module by hand.

Ok.

> Ideally, we should generate it automatically since this will prevent
> the docs for the Python interface to become out of sync with the C++
> implementation. However, there are some problems with this approach.
> 
> 1) The syntax in the C++ examples needs to be dealt with
> 2) Classes/functions are renamed/ignored (added?), we will need to
> look in the *.i files to figure out what to do
> 3) Overloaded functions are handled using '*args', we need to extract these
> 4) Other problems that I'm unaware of

Yes, these are all nasty one...
 
> The current content (in docstrings/dolfin/cpp.py) is just a copy of
> the old docstrings which was generated by 'generate_docstrings.py'
> since we didn't have time to write proper docstrings for the entire
> module. Only the Mesh class is currently documented and we need to add
> proper documentation for the rest.
> 
> The generate_docstrings.py uses xml output from Doxygen to write the
> docstrings.i, this is relatively slow, but once the docstrings module
> is in place we can generate docstrings.i using this module which
> should be fast. (Actually, we can already do this now since the module
> is complete w.r.t. functions/classes).
Ok.

Johan


> Kristian
> 
> > I couldn't figure it either. It would be good to have some more comments
> > in the code and some README files explaining what generates what.
> > 
> > Garth
> > 
> >> Is the goal to automate the generation of the the docstrings in this
> >> module, similare to what we have in C++?
> >> 
> >> This is probably something you allready have discussed, but it has been
> >> difficult to keep track...
> >> 
> >> Johan
> >> 
> >> 
> >> 
> >> _______________________________________________
> >> 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