Discuss alternatives to sphinx
Discuss alternatives to sphinx
Blueprint information
- Status:
- Complete
- Approver:
- None
- Priority:
- Undefined
- Drafter:
- None
- Direction:
- Needs approval
- Assignee:
- None
- Definition:
- Obsolete
- Series goal:
- None
- Implementation:
- Informational
- Milestone target:
- None
- Started by
- Completed by
- Adam Collard
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:/
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://
Jekyll
~~~~~~
- http://
- Static site generator
- Uses markdown for pages
Nikola
~~~~~~
- http://
- Static site generator