fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Monday March 29 2010 04:28:24 Kristian Oelgaard wrote:
> On 29 March 2010 12:55, Anders Logg <logg@xxxxxxxxx> wrote:
> > 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.
> 
> A last (for now) remark on the doc-strings, when generated in a separate
> folder/project I think the doc-strings for the dolfin module should be
> dumped in a module say docs.py and copied to the correct location in the
> DOLFIN source tree manually to avoid a dependency between the two
> projects. 

Agree, or maybe docstrings.py?

> Also, do we want to handle doc-strings for the pure Python
> projects like FFC, UFL etc. in the same way or should we extract
> documentation from doc-strings as these modules have a much more shallow
> tree structure which makes the documentation more manageable, or should we
> strive to keep things uniform across the projects?

Maybe use docstrings for now, and if it get out of proportion, which I do not 
think it will, we can consider putting it in its own documentation files. 

Johan


> Kristian
> 
> >> >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
> > 
> > -----BEGIN PGP SIGNATURE-----
> > Version: GnuPG v1.4.9 (GNU/Linux)
> > 
> > iEYEARECAAYFAkuwhwYACgkQTuwUCDsYZdGWjQCgkFKOJlIsJimnd+2dbgsphvH5
> > S+4Anjx+VFRlAQ6mkR0VwPTqwvWQJ/8b
> > =BQaF
> > -----END PGP SIGNATURE-----