Documentation templates (html/stylesheet)

Question

Hello!

Looking for some kind of documentation template. I want to markup my documentation in html and have a good looking style (stylesheet) for it. I don't looking for template in terms of how you write certain software documents.

<h3>Javascript function 1</h3>
<code class="javascript">code...</code>

<p class="tips">Something smart about this function</p>

Hope someone understands what I´m looking for. Thanks

Answer 1

For very long on-screen text I normally use the Easy-2-Read Standard.

Don't forget a print stylesheet! If I'm required to read long documentation I'd much rather print it out than read it on screen. If you're set with going the HTML/CSS route, instead of a regular document, remember to account for this.

Answer 2

I use Sandcastle

http://blogs.msdn.com/sandcastle/

and SHFB as a UI

http://www.codeplex.com/SHFB

Answer 3

I like the style of thhe djangobook, and the CSS frameworks tripoli and typogridphy

Answer 4

You could use the patterns and practices documentation tools http://www.codeplex.com/doctools

Although it uses Word 2007, but it has a nice toolbar.

Answer 5

Google has a nice clean way of doing it. In case you want ideas on how to lay it out.

e.g Google KML Code Documentation layout

Answer 6

I suggest you have a look at the Sphinx project: http://sphinx.pocoo.org/

With Sphinx, you mark up you documentation using reStructuredText. Sphinx converts the documentation to HTML, Latex (which can be used to create nice-looking pdf documentation) or MS HTML Help format.

Examples of Sphinx documentation:

• http://docs.python.org
• http://matplotlib.sourceforge.net/
• more...

Since Sphinx is written in Python, most of the projects currently using Sphinx are Python-related. Sphinx is however a general-purpose documentation platform, well-suited for most documentation tasks, I would imagine.

I have found Sphinx easy to use, and able to produce very nice-looking HTML documentation.

Some key points, from the Sphinx website:

• Output formats: HTML (including Windows HTML Help) and LaTeX, for printable PDF versions
• Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information
• Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
• Automatic indices: general index as well as a module index
• Code handling: automatic highlighting using the Pygments highlighter
• Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules, and more