fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Fri, Sep 03, 2010 at 10:20:16AM +0200, 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'
> 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).

Do we have any functionality in place for handling documentation that
should be automatically generated from the C++ interface and
documentation that needs to be added later?

I assume that the documentation we write in the C++ header files (like
Mesh.h) will be the same that appears in Python using help(Mesh)?

But in some special cases, we may want to go in and handle
documentation for special cases where the Python documentation needs
to be different from the C++ documentation. So there should be two
different sources for the documentation: one that is generated
automatically from the C++ header files, and one that overwrites or
adds documentation for special cases. Is that the plan?

Another thing to discuss is the possibility of using Doxygen to
extract the documentation. We currently have our own script since (I
assume) Doxygen does not have a C++ --> reST converter. Is that
correct?

--
Anders