fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.

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

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

This is very much a question of taste and it may sometimes be
difficult to find a rationale for all opinions (my own included) so
discussions are welcome.

--
Anders


> Kristian
>
> >Any comments or suggestions are welcome. Things are still up for
> >discussion but I hope Kristian can get started soon on building the
> >documentation.
> >
> >Even though Kristian will have the main responsibility for
> >coordinating and writing most of the documentation, I hope we can all
> >help out to create some really good documentation. For example,
> >Kristian could assign tasks for people to document certain functions,
> >or ask for help with proofreading.
> >
>

Attachment: signature.asc
Description: Digital signature