POWERMAN
"In each of us sleeps a genius...
and his sleep gets deeper everyday."

Abstract

Here is what I think about good and usable documentation system:

  1. It should be possible to write documentation on your workstation, in your favorite text editor, and it should not require access to internet.

  2. All documentation should be shared between authorized people. This include both accessing documentation using web browser and url in our server and accessing it in the local files.

  3. It’s nice to have ability to use simple markup language and hyperlinks in documentation to make documentation ease to read and navigate.

  4. Ability to edit documentation on server using web browser (a-la Wiki) may be required in some projects, but in most cases it’s needless.

Solution

Documentation for project stored inside project root directory, in .lib/doc/ directory (and it subdirs) in .txt files. Documentation distributed just like any other project’s files.

These .txt files written using simple markup language: AsciiDoc. See AsciiDoc markup cheat sheet.

Documentation is accessible using /doc/ url on project’s website. Access to /doc/ can be protected using .htaccess.

Note .html version of .txt files in .lib/doc/ will be generated automatically, and will be regenerated again if source .txt file was changed.

Configuration

AsciiDoc Installation on Gentoo Linux

emerge asciidoc

Vim syntax highlight

  1. Download asciidoc.vim and save it into \~/.vim/syntax/.

  2. Add something like this into \~/.vimrc: 

    autocmd FileType mail,text,asciidoc,html setlocal spell spelllang=en,ru
autocmd FileType asciidoc
        \ setlocal autoindent expandtab softtabstop=2 shiftwidth=2
        \ formatoptions=tcqn
        \ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
        \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:>
Tip
Perl and sh code inside asciidoc files can be highlighted this way:
[source,perl]
----
print "ok\n";
----

[source,sh]
----
echo ok
----

Viewing documentation in browser

Download latest asciidoc.cgi. You’ll find documentation about installation and configuration inside it.