[IPython-user] Time for documentation infrastructure overhaul?

Nicolas Pernetty nicopernetty@yahoo...
Tue Aug 21 18:08:21 CDT 2007

On Tue, 21 Aug 2007 23:55:24 +0200, Stefan van der Walt
<stefan@sun.ac.za> wrote :
> > > > Yes, I've been looking into this recently already, esp. now that
> > > > python-dev made the transition, so much of the groundwork is
> > > > now done and (hopefully) reasonably tested.  The person who did
> > > > the lion's
> > >
> > > Ah, I see. It's a rather recent, but apparently succesful effort.
> > > Places to look:
> > >
> > > http://svn.python.org/projects/doctools/ (the actual software)
> > 
> > I've now tried this tool, and I have to say it's probably easier to
> > write a direct custom mapping from LyX to ReST than it would be to
> > hack the doctools utility for our purposes. Luckily the LyX syntax
> > used seems to be rather simple.
> Here's a link to a docbook -> rst converter (LyX can export to
> docbook):
> http://thread.gmane.org/gmane.text.docutils.devel/4121
> An easier approach may be Pandoc:
> http://sophos.berkeley.edu/macfarlane/pandoc/
> """
> Pandoc is a Haskell library for converting from one markup format to
> another, and a command-line tool that uses this library. It can read
> markdown and (subsets of) reStructuredText, HTML, and LaTeX, and it
> can write markdown, reStructuredText, HTML, LaTeX, ConTeXt, RTF,
> DocBook XML, groff man, and S5 HTML slide shows.
> """


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

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...).


More information about the IPython-user mailing list