fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Mar 29, 2010 at 12:19:22PM +0200, Kristian Oelgaard wrote:
>
>
> On 26 March 2010 19:10, Anders Logg <logg@xxxxxxxxx> wrote:
> >On Fri, Mar 26, 2010 at 02:19:31PM +0100, Kristian Oelgaard wrote:
> >>
> >>
> >>On 23 March 2010 20:59, Anders Logg <logg@xxxxxxxxx> wrote:
> >>>It looks like we have converged towards reST/Sphinx to be used for
> >>>both the C++ and Python interfaces, as well as for docstrings.
> >>>
> >>>I have summarized some of my conclusions here:
> >>>
> >>> https://blueprints.launchpad.net/fenics-doc
> >>
> >>Looks good, the only thing I don't agree with (possibly because I
> >>don't understand it) is why we will use reST and Sphinx to generate
> >>the doc strings for the Python modules.  As I see it, Sphinx focuses
> >>on handwritten documentation with the ability to auto-generate
> >>documentation from doc-strings if needed. So I don't see a use for
> >>generating a doc-string in Sphinx and then add it to some function,
> >>what good will that do anyway to a developer who has opened a *.py
> >>file to modify it?
> >
> >The motivation is the following:
> >
> >1. We want to split out the documentation so that it is not part of
> >the code. The reasons for this are:
> >
> > 1.a) It may otherwise be hidden deep inside the code and difficult
> > to edit, the prime example being the documentation of Expressions in
> > Python, which is now hidden deep inside a very complex piece of
> > code that handles the metaclass magic for Expressions.
> >
> > 1.b) It may otherwise clutter the code (especially for the otherwise
> > clean C++ header files) and result in something like 90%
> > documentation and 10% code. Then it's not code with documentation,
> > it's documentation with some function declarations here and there.
> >
> > 1.c) It's easier to edit, spell-check, grammar check, translate etc
> > if it is maintained separately.
>
> I agree to all this, so instead of the rather extensive doc-strings
> we have now, we will just have one-liners (which will be overwritten
> when importing the dolfin module) like we have in the C++ part of
> DOLFIN to help developers working in the source files.

Yes, something like that. It can either be one-liners or it can be
empty. I'm not sure which is best.

> >2. The same documentation should appear in the docstrings (when typing
> >help(Expression) or help(assemble) in Python) as in the manual (to
> >avoid duplication of effort). Since by (1) we don't extract the
> >documentation from the code, we must either do the opposite (which I
> >prefer), or generate both documentation and docstrings from a third
> >source (using a preprocessor as suggested by Hans Petter).
>
> I also prefer Hake's suggestion.
>
> >>As far as I can tell, Sphinx can't process doc strings from C++, but
> >>there might be some workarounds using Doxygen if we decide that we
> >>need it, otherwise we can still use Sphinx and simply write
> >>everything by hand.
> >
> >We could use the Breathe (as pointed out by Andy) but my suggestion
> >would be to have hand-written documentation (and then some script to
> >check for missing documentation). Perhaps there's a way to use Doxygen
> >to extract the function signatures and the one-line compact comment,
> >then fill in the rest by hand.
>
> Sounds like a lot of work to get just one line of documentation, if
> we can just run a script to check for functions/classes with missing
> documentation, that will be enough.

Agree.

--
Anders

Attachment: signature.asc
Description: Digital signature