[IPython-user] Time for documentation infrastructure overhaul?

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


On Wed, 22 Aug 2007 01:08:21 +0200, Nicolas Pernetty
<nicopernetty@yahoo.fr> wrote :

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

Oh and MoinMoin is able to generate simple Docbook directly
(http://moinmoin.wikiwikiweb.de/DocBook) which may be very handy for
those who want to stick with wiki...



More information about the IPython-user mailing list