fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Sep 06, 2010 at 12:19:03PM +0200, Kristian Ølgaard wrote:

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

ok.

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

It would not be difficult to make the documentation extraction script
we have (in fenics-doc) generate the docstrings module and just
concatenate all constructor documentation. We are already doing the
parsing so spitting out class Foo: """ etc would be easy. Perhaps that
is an option.

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

If we can make it 99% automatic and have an extra file with special
cases I think that would be ok.

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

I agree. :-)

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

Perhaps an idea would be to use Doxygen for parsing and then have our
own script that works with the XML output from Doxygen?

  1. Use Doxygen to generate XML
  2. Generate docstrings/dolfin/cpp.py from XML
  3. Generate C++ reST from XML
  4. Generate Python reST from XML

--
Anders