Re: Documentation tools and standards?

[Maurizio Tomasi <ziotom78@gmail.com>]

On Friday, December 13, 2013 10:23:43 PM UTC+1, Diogenes wrote:
> As far as the technical documentation...do you guys typically use Doxygen,POD,NDoc, etc..? Which one seems to work best for you?

I do not like very much to interweave large chunks of documentation with the code, so instead of using tools like Doxygen I usually write the documentation separately.

I have used Sphinx (http://sphinx-doc.org/latest/) many times and I must say I really like it. Although it is python-centered, it can work with other languages as well. The "sphinx-contrib" package includes a number of plug-ins (https://bitbucket.org/birkenfeld/sphinx-contrib), and one of them ("adadomain") adds support for Ada.

To see how the documentation looks, see here (selecting "Show source" from the menu on the left will show you the input file used to produce the documentation):

http://docs.python.org/2/reference/index.html

From my point of view, a nice feature of Sphinx is its support for ReadTheDocs (https://readthedocs.org/), a site which allows to publish online your documentation (obviously this is ok only if your project is open source or public domain). ReadTheDocs implements its own Sphinx style, which I like more than the default one. The repository is available on GitHub (https://github.com/snide/sphinx_rtd_theme). As an example of the style (and indirectly of the theming capability of Sphinx), here is the documentation I am writing for a small C library I am developing in my spare time:

http://hpixlib.readthedocs.org/en/latest/introduction.html


Cheers,
  Maurizio.