fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Sat, Mar 20, 2010 at 04:10:53PM +0100, Hans Petter Langtangen wrote:
> Sat, 20 Mar Anders Logg wrote:
>
> > > >We have also discussed using a standard format for the Python Docstrings. So
> > > >nice programmers references can be generated from these. We haven't decided
> > > >which one we are going to use (epydoc or others). I couldn't find doconce (too
> > > >close to many other meanings of doc once :P) at the net so I do not know what
> > > >this software does or how well adapted it is.
> >
> > Perhaps Hans Petter could say something about doconce?
>
> I wrote doconce during the FEniCS'06 (?) meeting in Delft :-) as a
> solution to the problem that I wanted to document software in one
> place only, and still be able to put that single piece of text into
> pure source code, latex manuals, html manuals, other formats like
> docbook, etc. There is and was a relevant tool, docutils and the reST
> (restructured text) markup, for doing this. The problem with docutils
> was that I think reST has too much markup compared to the plain text
> you want to see in the source code and with pydoc in a
> terminal. Writing a new backend in docutils that filters reST to plain
> (almost) untagged text is the obvious solution, but that seemed
> very complicated. I also wanted better support for source code and
> mathematics in documents. The attached tutorial explains what doconce is.

It looks pretty cool and I very much like the idea of a simple
text-based format that looks natural (very similar to Publish).

But how would it be used to document code? Is the doconce input
written as part of the code, or is the code generated as the result of
some preprocessing stage?

> > It might have some good features we can use. But one issue would be
> > the status of doconce. To be useful, it needs to be actively
> > maintained and widely available (as in having a Debian package).
>
> Right now it's living in Simula's svn repository only. It has been
> frequently used by myself and others (Johannes, Ilmar). We have thought
> of putting it out on googlecode, but that requires maintenance...
>
> For example, my latest book has half a chapter where the source is in
> doconce.  That source is automatically copied into a doc string in the
> Python code, so that we have the book material also as documentation
> of a Python module (via pydoc), the source is filtered to Epytext and
> included in the Python module to produce an Epydoc manual of the
> module, the source is also filtered to HTML for an online tutorial,
> and to latex for fancy typesetting in the book (and in fact also
> Johannes Ring's master thesis). The idea is to document once and only
> once: if the tutorial is updated, it's the doconce source, and I have
> automatic update of the book, the Python source code, and other
> manuals :-)
>
> Personally, I use doconce for almost everything I write (except slides
> and complete books) since that enables me to postpone the choice of
> format.
>
> Johannes (who have made a wiki filter to doconce and done many other
> adjustments) and I could maintain a more official version and maybe
> try to get it into Debian. However, we should carefully consider the
> work associated with a more official version. Doconce is very limited
> (no footnotes, no citations and bibliography, for instance) and as
> soon as it gets users, they will demand extensions.  The point was to
> make it minimal. Debugging errors can also be somewhat frustrating
> and challenging.
>
> FEniCS should definitely adopt the doconce *strategy*, i.e., write a
> piece of text only once, but maybe distutils and reST is a better
> technical choice?  The downside is no support for math, you cannot
> copy code directly from a source file and into a manual, and the reST
> tagged text (sometimes a bit ugly) appears in Doxygen text or Python
> doc strings. The upside is strong support.
>
> > I think we need to separate demos from tutorial/example programs. The
> > demos should be as they are now: short, simple and self-explaining.
> >
> > Then we can have a different set of programs which are explained very
> > carefully. It would be natural for these to be part of the tutorial
> > (based on the existing tutorial written by Hans Petter).
>
> I share this view. You copy demos and modify to solve a new problem.
> Tutorial examples are made for teaching ideas, syntax, etc. The code
> therefore often becomes quite different from a self-explaining demo.
>
>
> > > >>2. Both the user manual and tutorial will come in two different
> > > >>flavors, one C++ and Python. With some clever use of LaTex \input, it
> > > >>should be possible to handle with not too much extra work.
>
> I use a program preprocess (in Python :-) to allow for #ifdef and other
> C preprocessor type of commands in latex, shell, doconce, and almost
> whatever. Then it's easy to compile a tutorial in one mode. (At the
> University of Oslo this is used for compiling course manuals with
> Python or Matlab.)
>
> But I doubt that #ifdef or clever \input is the way to go with Python
> and C++ in a tutorial. The text will naturally be quite different for
> the Python and C++ versions. I think it's better to explain most of
> the things in Python first and then provide add-on material for
> C++. This can be made quite short with a focus on syntax, and reference
> back to where the example is introduced in the Python part. However,
> if you have a substantial amount of users who don't want to use or
> read about the Python interface, you need a stand-alone C++
> tutorial. In my view, FEniCS users should normally use Python for
> rapid development, but turn to the C++ interface for speed in a more
> comprehensive code. That is, the C++ FEniCS programmers are quite
> advanced users already and you can take advantage of that when writing
> tutorial material. (For the Python tutorial, I forsee very novice
> users who don't know finite elements and Python, but they have a PDE
> to solve...it seems that FEniCS can, maybe uexpectedly, work well
> for this group of users.)

I think we have some C++ only users that don't care much for the
Python interface and some Python users that absolutely don't want to
see the C++ interface, so I think it would be good to split the two
manuals. But you are probably right that the two texts will be
different. Instead of one document with #ifdefs, it should perhaps be
two different documents that share some common chapters that are
language independent.

> > > >>6. We need well-documented demos. It's currently unclear what the
> > > >>relation is between the manual, documented demos, current demos in
> > > >>DOLFIN and the examples in Hans Petter's tutorial so we need to work
> > > >>out a model for this.
>
> I suggest to view the manual, tutorial and demos as three different
> types of documentation. The tutorial has its example programs, so may
> the manual (but I guess there will be more of short code snippets in a
> manual), and the demo selection is a third source of information. To
> me it seems difficult to maintain these three types of documentation
> if they are closely related to each other.

Agree. And the "well documented examples" discussed above should be
part of the tutorial. I think we are looking at the following pieces:

  1.a FEniCS Tutorial (C++)
  1.b FEniCS Tutorial (Python)
  2.a FEniCS User Manual (C++)
  2.b FEniCS User Manual (Python)
  3.a Demos (C++)
  3.b Demos (Python)

1 and 2 should be available in both HTML and PDF.

1.a and 1.b can be created based on the existing C++/Python tutorial.

3.a and 3.b are in pretty good shape already and can remain where they
are (as part of the DOLFIN source tree), but some demos are missing in
C++ and others in Python. We might also consider making the demos more
easily accessible via the web page. They may be difficult to find,
especially for someone using the Debian/Ubuntu packages (where they
are located somewhere under /usr/share/doc).

The question is how to design 2, the user manual, whether it should be
generated from the code, or if it should be written manually.

A related question is if we need a FEniCS Programmer's Reference and
how that differs from the User Manual, or if the User Manual should
contain everything and make a Programmer's Reference unnecessary.

--
Anders

Attachment: signature.asc
Description: Digital signature