fenics team mailing list archive

["Garth N. Wells" <gnw20@xxxxxxxxx>]

On 03/09/10 09:20, 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.
> 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
>
> The current content (in docstrings/dolfin/cpp.py) is just a copy of
> the old docstrings which was generated by 'generate_docstrings.py'

Does this mean that I should be able to run 'generate_docstrings.py'? I 
get the error

Traceback (most recent call last):
  File "generate_docstrings.py", line 458, in <module>
    g.generate_interface_file_from_index()
  File "generate_docstrings.py", line 432, in 
generate_interface_file_from_index
    dfile = open(self._docstring_file,"w")
IOError: [Errno 2] No such file or directory: 
'/home/garth/code/fenics/dolfin.d/dolfin-all/dolfin/swig/swig/swig_docstrings.i'


when I run it.

Garth

> 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).
>
> 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