Documentation Markup

[Geoff Leyland <geoff_leyland@...>]

Hi,

I'm about to start improving the documentation for Rima (a tool for  
building math models and a binding to LP solvers), and it seems like  
two tools would be really useful:


1) The documentation is in markdown (is that a good choice?) and has  
code examples like:
[[
You can treat expressions just like variables:

    x, y = rima.R"x, y"
    e = x * y
    =e * x * y                                          --> x*y*x*y
]]
What would be really cool would be a tool that read the markdown file,  
found all the code blocks, ran them and checked that the output  
matched the comment.  It would me even cooler if it syntax-coloured  
the Lua code (not that there's much to colour in the example above).


2) I have some example files with comments explaining what they do.  A  
tool that ran over the file, and turned it into a markdown document  
with the lua code embedded in it would be fantastic too.  I'm not  
talking about a doxygen or LuaDoc type thing, I'd want the full text  
of the example file, just kind of turned inside out.


Before I start hacking together a rudimentary implementation, does  
anyone know if such things already exist?

Cheers,
Geoff