fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 6 September 2010 11:53, Anders Logg <logg@xxxxxxxxx> wrote:
> 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?

No, not really.

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

Yes and no, the problem is that for instance overloaded methods will
only show the last docstring.
So, the Mesh.__init__.__doc__ will just contain the Mesh(std::str
file_name) docstring.

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

The plan is currently to write the docstrings by hand for the entire
dolfin module. One of the reasons is that we rename/ignores
functions/classes in the *.i files, and if we we try to automate the
docstring generation I think we should make it fully automatic not
just part of it.
Also, we will need to change the syntax in all *example* code of the docstrings.
Maybe it can be done, but I'll need to give it some more careful
thought. We've already changed the approach a few times now, so I
really like the next try to close to our final implementation.

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

I don't think Doxygen has any such converter, but there exist a
project http://github.com/michaeljones/breathe
which makes it possible to use xml output from Doxygen in much the
same way as we use autodoc for the Python module. I had a quick go at
it but didn't like the result. No links on the index pages to function
etc. So what we do now is better, but perhaps it would be a good idea
to use Doxygen to extract the docstrings for all classes and
functions, I tried parsing the xml output in the
test/verify_cpp_documentation.py script and it should be relatively
simple to get the docstrings since these are stored as attributes of
classes/functions.

Kristian

> --
> Anders
>