[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.
> """

Hello,

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

Regards,


More information about the IPython-user mailing list