[IPython-user] Time for documentation infrastructure overhaul?

Fernando Perez fperez.net@gmail....
Tue Aug 21 23:51:21 CDT 2007


Hi Nicolas,

On 8/21/07, Nicolas Pernetty <nicopernetty@yahoo.fr> wrote:

> May I humbly suggest using Docbook ?
> Docbook can be directly converted to HTML (using simple xsltproc) and
> can be easily converted to LaTeX (and so PDF) using dblatex
> (http://dblatex.sourceforge.net/).
>
> Dblatex is written in Python and is actively maintained by his very
> responsive author.
>
> Using Docbook/XML you can be as modular as you want and still retained
> the ability to generate individual documents as well as the whole.
>
> I'd give a hand to convert Ipython docs to Docbook if you want (but I
> don't know reStructuredText...).

Many thanks for the offer, but I think that docbook is going in the
opposite direction that we want.  I suspect that if people found
editing LyX was a hurdle, Docbook isn't going to fare a whole lot
better.  As Stefan mentioned, Lyx can already write out docbook, so we
could be using that today if we wanted.

But the point is to have the docs in a simple, plaintext format that
is easy to edit with any editor and minimal markup.  The ipython docs
need to be functional but not a work of art in typesetting, and we
have no complex mathematics to worry about (the uncontested domain of
latex/lyx).  I wrote the original manual in Lyx simply because I write
*everything* in latex/lyx, but I realize that's not a very common
workflow in other fields.  And recently I've become quite fond of
reST: it's trivial to pick up, anyone can just type it in without
markup and it works correctly, and prettyfing contributions to
complete the markup is very easy (at least with Emacs' superb reST
mode).

The fact that the core Python team has gone with this toolchain is
also a plus to follow this direction: the more standard tools we use,
the better supported we'll be, since we can ride on their efforts.

Maintaining the docs is something that should be as low effort as
possible, else it will take already limited resources away, or simply
won't get done.

I'll be glad to entertain the views of others if you think that
docbook would make life easier, but I'll need to hear very good
arguments on how a docbook-based workflow would be a LOT easier than
Lyx/latex.

regards,

f


More information about the IPython-user mailing list