for quite some time I was thinking about way we provide documentation
and I think there is lot of place for improvements.
As my current favorite tool to build documentation is Sphinx
<http://sphinx.pocoo.org/>, I gave it a try. To name some of the
benefits let me quote from their home page:
* Output formats: HTML (including Windows HTML Help), LaTeX (for
printable PDF versions), manual pages, plain text
* Extensive cross-references: semantic markup and automatic links for
functions, classes, citations, glossary terms and similar pieces of
* Hierarchical structure: easy definition of a document
tree, with automatic links to siblings, parents and children
* Automatic indices: general index as well as a module index
* Built-in fulltext search
I've done quick and dirty [*] conversion of FAQ and few introductory
sections, you can find source here:
And the generated documentation in HTML and PDF here:
What do you think about changing our documentation from HTML to
something else (be it Sphinx, Docbook or something completely else)?
[*] I've lost all text formatting and links in text, but that should
not be hard to convert properly, I just did not want to spend much time
this Sphinx format seems easy to work with; it would be a good improvement.