Am 13.11.2009 um 12:56 schrieb Nigel Metheringham:
>
> On 12 Nov 2009, at 22:31, Mike Cardwell wrote:
>
>> It's much simpler to just use the Apache mod_xslt module:
>
> This will require all sites that mirror the documentation to have
> the same config. They may not be running apache.
>
> I would be very wary about making changes that require more
> intelligence from the web server than shovelling data straight off
> disk.
>
> Nigel.
I followed the discussion and thought I'd write up my suggestion.
Use the sphinx document generator (
http://sphinx.pocoo.org/). It is
well suitable for technical documentation, much simpler than docbook
et al., but not oversimplified (as in wikis). It can generate HTML,
PDF, plain text and other formats, all of which can be delivered by
web servers (and mirrors) statically. Or shipped for offline reading.
I implemented this for a project of mine (
http://mirrorbrain.org/
docs/), and I couldn't be happier with it. The main objective for me
was to invite people to contribution and don't place obstacles in
their way (like learning complicated techniques).
http://mirrorbrain.org/docs/intro/#how-to-improve-this-documentation
describes how one would go and edit the documentation. The source
code of the very same page is straightforward:
http://svn.mirrorbrain.org/svn/mirrorbrain/trunk/docs/intro.rst
The format is called reStructuredText and it is (IMO) a good
compromise of power and ease of use.
For me, one of the most interesting things was to create a post-commit
hook that automatically regenerates the documentation whenever I
change it in the source code repository. (I love short release
cycles.) That could easily be implemented. Otherwise, don't look too
much at my project page because it more or less is a one man show... A
better site to look at is the Django Project (
http://www.djangoproject.com/
) who use Sphinx for all documentation. And they have extensive docs
-- among the best I ever encountered in an Open Source project.
Their docs are "versioned". The top of the page often contains a hint
that links to other versions:
http://docs.djangoproject.com/en/dev/
"This document is for Django's SVN release, which can be significantly
different from previous releases. Get old docs here: Django 1.0"
http://docs.djangoproject.com/en/1.0/topics/db/
"This document describes Django version 1.0. For development
documentation, go here."
That's highly useful IMO, and it solves the initial problem presented
in this thread - that users end up in the wrong documentation for
their exim version, without noticing it and without link to the other
versions.
The different documentation branches shown on the web site correspond
to the different branches in the source code repository, for instance:
trunk:
http://docs.djangoproject.com/en/dev/topics/db/queries/
http://code.djangoproject.com/browser/django/trunk/docs/topics/db/queries.txt
1.0 release:
http://docs.djangoproject.com/en/1.0/topics/db/queries/
http://code.djangoproject.com/browser/django/tags/releases/1.0/docs/topics/db/queries.txt
That's all possible with the Sphinx framework. It should be quite
possible to copy the smart things from the Django project. For me,
this fulfills all needs that a documentation framework should offer:
* it's easy to work with as a developer
* it has a low barrier for contributors (developers and non-developers
alike)
* it's easy to get going but still very customizable
* it can be served statically and doesn't need special software and
scales well
Peter
