[Doc-SIG] [Python-Dev] The docs, reloaded

[Martin Blais]

On 5/20/07, Georg Brandl <g.brandl at gmx.net> wrote:
>  > Very nice! As well as looking very attractive and professional, the all-Python
>  > toolset should make it easier to build the documentation - I've not been
>  > able to get a trouble-free setup of the docs toolchain on Windows.
>
> Yep. As it is now, you need three packages from the Cheese Shop:
> Docutils, Pygments (the highlighter) and Jinja (the templating engine).
> This shouldn't be problematic, though they could also be stripped down
> and included.

This is great.  IMHO if this is to compete to become the official
Python docs, I would argue for even less dependencies, even at the
cost of more generic/bland output, for portability reasons and to
stimulate greater adoption.  If we can make some of those dependencies
optional and only rely on docutils, that could make it ubiquitous.

Another thing to keep in mind:  I don't know if the directives you
defined are very generic, but if they are, it would be interesting to
consider migrating them up into docutils (if it makes sense), and see
if they could support documenting other programming languages.  Could
this be a language-independent documenting toolkit?  Could we document
LISP or Ruby code with it?

Georg, thanks again!