For years, I've written documentation using ReStructured Text (RST). It's just one of several "lightweight markup languages ". For others, look at Markdown , StructuredText , Setext , among many others.
I generally use the rst2html utility that comes with Docutils . It works fine for small things.
I just read about the Sphinx documentation generator and I am totally hooked.
I spent a productive day making a bunch of small revisions to a big library of documentation to move it from some home-brewed rst2html tooling into Sphinx. I got to delete some boilerplate markup from a lot of files, delete some tools, and generally tidy up.
API Documentation
Sphinx says that they don't produce API docs. They're not epydoc .
Previously, all of my internal API documentation was done using epytext , but not for a great reason. Because Sphinx works in RST, I need to convert my internal documentation from epytext to RST.
At first, this looked painful. However, 90% of the changes are from @param this: some text to :param this: some text. The other 10% are some massaging of @todo: and @note:; partly to change @todo: to :todo: but also to change the indentation to RST rules.
Organizational Issues
My original home-brewed documentation had lots of complex cross-references. However, I couldn't bear the idea of putting all of the documents into some rational directory structure because all the links would break.
Sphinx tacks references across files, allowing me to define a name in one file and reference it in another. Problem solved. I can arrange and rearrange the components into an outline that actually makes sense for maintenance and management.
And nothing beats semantically rich pure text markup of RST as implemented by Sphinx. Documentation is fun when there are no barriers to entry.