Use sphinx or similar to generate useful reports from suite definitions

[cylc]

"Sphinx is a tool that makes it easy to create intelligent and beautiful documentation": http://sphinx.pocoo.org/
There's also "sphinx-report": http://code.google.com/p/sphinx-report/.

It was suggested at MPI, as I recall, that something like this would be good for generating human-readable metadata describing the suite as a whole, for archiving with experiment results.

Luis, would you like to add to this?

[m214089]

The basic idea is to have something like a printable report on how the suite looks like for the beginning. A good starting point would be a 'restructured' form of the suite.rc with added metadata, only those which could be retrieved 'automatically' like site, hosts, who, when, ... to file this. There is more and more pressure from the 'public' to be more
precise in documenting what is done. And this could help. I could offer to try to test something based on suite.rc outside of cylc and we can try later to extend that inside of cylc.

To a certain extend this sounds a bit silly, I know, but if you look into things like the CRU email 'scandal', it is getting evident that we must be more 'verbose' and 'clear' on what we do. And this could support the case.

[benfitzpatrick]

We're not sure that users need this kind of annotation to the few cylc builtin configuration options. There isn't a lot extra that could be added, as most options are fairly descriptive and people can add comments.

Closing for the moment - issue can be reopened based on demand.