Framework to write documentation

I have made it a habit to self-document the configuration settings (and idiosyncrasies) of programs I use, so that I can quickly reinstate them in case of a new OS installation, without having to chase manuals.

Currently, I do this in plain text format with a few symbols like brackets for special meaning. As the texts grow larger, I feel a need to switch to a more pleasant way to read and navigate them.

My current idea is to switch to "markdown" notation (or a fork of it) for the docs and then have a script build a tree of HTML pages from that. This way I could edit my files as before, but have something nicer for reading.

If you guys have any better suggestions, I'd love to hear them.

Well, I have been using Sphinx for a few years and don't plan to change for any reason. reStructuredText is better adapted to this type of work on which you want your technical documentation to follow a program structure and is a de facto documentation generator tool, the likes of Doxygen. Markdown is better suited as writing tool for vertical reading manuals, not documentation. Although once you get used to reStructuredText, you can (and you probably will want) to use it also for vertical writing material of any sorts, since the sphinx toolset offers tremendous ability in creating very nice looking reading material for the web or in offline formats. At the expense of a little more verbosity in the material source, but nothing to cry about.

Sphinx looks really good Mario, specifically these bullets:

• Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
• Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
• Code handling: automatic highlighting using the Pygments highlighter

I'll give it a test run with some dummy data.

As someone who's seen markdown used for documentation, I must agree with Mario, don't use markdown for actual documentation.

Granted, I know the documentation for something like the V8 API is generated with Doxygen but it sorely lacks an entry point if you're unfamiliar with the library. It's just lists things like all the classes, namespaces, etc. without any sort of helper info.

I just want to report back that I'm pretty satisfied with Sphinx, that was a good recommendation. It's not too difficult to set up and have version control on the user-written documents. Cheers!