Investigate use of dexy to write documented runnable demos

[Martin Sandve Alnæs]

http://www.dexy.it/

[Lawrence Mitchell]

FWIW, we use pylit (https://github.com/gmilde/PyLit) which just allows you to write normal rst (as one would for sphinx).

For example see http://firedrakeproject.org/demos/camassaholm.py.html, with associated runnable demo file: http://firedrakeproject.org/demos/camassaholm.py

And the input documentation: https://raw.githubusercontent.com/firedrakeproject/firedrake/master/demos/camassa-holm/camassaholm.py.rst

[Martin Sandve Alnæs]

Is it python only?

[Lawrence Mitchell]

No, it's just a bidirectional converter. It basically takes rst marked up documents that contains code-blocks and turns everything but the code blocks into comments, so you get a compilable file. The opposite direction also works.

[Martin Sandve Alnæs]

So you can edit as rst, convert to py, test and edit as py, convert back to rst, etc? Would it work if the source is split over e.g. a .ufl file, a .h file, and a .cpp file?

[Lawrence Mitchell]

Definitely yes to the former. I think possibly yes to the latter. You might have to have makefile rules that know what things live together.

[Anders Logg (Chalmers)]

Removing milestone: 1.8 (automated comment)

[Prof Garth Wells]

We're using pylit.