Discuss alternatives to sphinx

MAAS Documentation infrastructure
=================================

Problems with Sphinx
--------------------

 - It's restrictive; the structure is rigid and it's hard to break out of
 - The standard way of organisation is not nice, and makes it hard to find things
 - Search doesn't work.
 - The syntax is fiddly and needs frequent references to the cheat sheet.
 - The autodoc stuff never seems to work quite how you expect it to.
 - It's hard to machine-generate the stuff; the escaping rules are unclear - the format is not properly described.

Requirements for a replacement
------------------------------

 - Machine generation of the API docks
 - We want Nick to be able to be expressive and eloquent and erudite and other things beginning with e.
 - Render to HTML and some other console-accessible format (man pages, for example).
 - The ability to numbered walkthrough.

Possible alternatives
---------------------

Manually writing stuff
~~~~~~~~~~~~~~~~~~~~~~
 - Use a script to generate API documentation.

DoxyGen
~~~~~~~
 - Allows you to generate documentation from code
 - You can also add non-code-generated documentation.

DocBook
~~~~~~~

 - Very powerful
 - XML-based. Screw that noise. You might as well just write HTML yourself.

Gollum
~~~~~~
 - https://github.com/gollum/gollum

Mallard
~~~~~~~
 - XML-based but with a small syntax
 - Some control over presentation; support for images and rollovers.
 - Driven with XSL.
 - Good tool support - every language supports XML
 - http://projectmallard.org/

Jekyll
~~~~~~
 - http://jekyllrb.com/ (python version is Hyde http://ringce.com/hyde)
 - Static site generator
 - Uses markdown for pages

Nikola
~~~~~~
 - http://getnikola.com/
 - Static site generator