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 _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
