fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Friday September 3 2010 01:31:38 Garth N. Wells wrote:
> 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_docstrin
> gs.i'
> 
> 
> when I run it.

The error come because running the script from the konsole assume a predefined 
directory structure. By importing DocstringGenerator you can set these 
direcories, which we do in generate.py, as Kristian writes.

Johan
 
> 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