fenics team mailing list archive

[Hans Petter Langtangen <hpl@xxxxxxxxx>]

Mon, 22 Mar Anders Logg wrote:
> I'm probably missing something here, but I don't see much difference
> between the reST and doconce input. Take for example the following page:
> 
>   http://sphinx.pocoo.org/rest.html
> 
> The reST input can be viewed by clicking "Show Source" in the right
> column. What would the corresponding input look like for doconce?

Very, very similar! There are only some small differences for making
it easier to parse the text with regular expressions (which I use for
simplicity, but that's sometimes a real hazzle). 

There are a couple of features of doconce that I wanted to have: 
1) copying of source code from files, with specification of a certain
style of typesetting the code (in LaTeX), and 2) better support for
equations and inline math so that the math comes nicely out in LaTeX.
Doconce has special paragraphs for code and math, so this is the
biggest (and almost only) syntax difference from reST.  These
constructions are nice things if you work on some document where the
final format is unclear, but LaTeX (=book/paper) is very likely. Over
the years I've written a lot of educational material that have ended
up in LaTeX books, but started it's life as doconce text and lived for
a while in HTML, some parts also as Epytext and plain text for Python
(module/package) doc strings. The ugly LaTeX from reST was not
suitable for (my) books ;-)

For FEniCS documentation you don't need that flexibility, and you have
more emphasis on HTML output than LaTeX or other formats. Then reST
is definitely the answer! This is my clear conclusion now after having
thought about it for a few days :-) Sphinx + reST! (If it's okay for C++ too)

> I'm not too keen on not editing the source files directly, but from
> what I understand, you do this to make things work with docstrings in
> Python? Then this can be avoided by Johan Hake's trick (assigning some
> appropriate output from doconce to __doc__).

Sure, Python can preprocess itself - I do that a lot. One example is
to list all options of various kinds in static class variables, use
these lists (or dicts) for checking input in the code and provide nice
error messages, while these lists can also be formatted nicely and
inserted automatically in doc strings so that you always have an
updated list of what's possible in a class or function when you
process the doc string (pydoc, help in the interpreter, Epydoc, I
guess it works with sphinx too). Just the import statement does all
the processing. Large sections of text that goes into various
documents, can either be preprocessed (#include) or loaded into doc
strings at import time (the latter strategy takes more time and is not
my personal favorite, but that's just a matter of taste - I'm very
much a preprocessing guy).

Hans Petter