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
