Huw Davies <huw.davies@kerberos.davies.net.au> writes:
I’m in the process of building a number of somewhat more complex Linux (Centos) SAN based environments. I need to document the storage layout (from the physical disk layout right through to the filesystems in their various volume groups) and hoped someone had a pointer to a tool that could produce nice, preferably HTML, documentation automatically.
I have in the passed used a tool on AIX that did almost what I needed but adopting it for Centos would be very challenging (especially as it was written in Perl and I’m more of a Python guy).
Who is the target audience of this documentation? e.g. end users, managers or devs? What is the nature of the documentation? e.g. is it a user manual, API documentation, FR, technical design,...? These questions inform what tool you use. For non-dev/non-API docs, I have best results using reStructured Text -- it has a more rigorous and complete feature set than markdown, and it has an explicit IR (so multiple output formats are natural). For more formal deliverables I render it using python-sphinx, which extends rst (backwards-incompatibly) with some tech writing features -- the main one I use being the "toctree" directive. I prefer to build the PDF's via sphinx's default latex theme, though rst2pdf can rend directly (thus fewer dependencies). rst support in non-Python languages is usually aggravatingly feature-incomplete, e.g. (as at last time I checked) gitit (Haskell) doesn't support obvious things like definition lists, let alone Emacs' M-x table-insert compatible tables with row and column spans. If I need math or bib, I use LaTeX. For diagrams, I wish I still had access to OmniGraffle[0]; I tend vacillate between graphviz, inkscape, dia, pic and ascii art, depending on my mood and the kind of diagram I want. [0] non-free, OS X only.