Discuss alternatives to sphinx

Registered by Julian Edwards on 2013-10-22

Discuss alternatives to sphinx

Blueprint information

Status:
Not started
Approver:
None
Priority:
Undefined
Drafter:
None
Direction:
Needs approval
Assignee:
None
Definition:
New
Series goal:
None
Implementation:
Informational Informational
Milestone target:
None

Related branches

Sprints

Whiteboard

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

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.