[IPython-user] Time for documentation infrastructure overhaul?

Ville M. Vainio vivainio@gmail....
Tue Aug 21 13:10:49 CDT 2007


On 8/21/07, Fernando Perez <fperez.net@gmail.com> 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)

http://www.nabble.com/-ANN--Python-documentation-team-looking-for-members%21-p11722193.html

> Unfortunately it seems that having LyX-based docs (which is freely
> available for Win32 and OSX) is a barrier for many, and there's
> nothing I can do to change that.

One barrier is that it's one external tool that is needed, as opposed
to just depending on something that can be easy_install:ed. ReST is
also usable as-is (without conversion of any kind), which is a big
plus.

> - Export the existing manual and new_design documents from latex to
> reST, using the tools from Python-dev.  This might require asking
> Georg Brandl, I don't know where the tools are.

This should be a sufficient first target; as you say, this is
necessarily a gradual process and  we can publish intermediate results
like the ReST file. After that, edits/improvements can be done there
while we continue to publish the pdf file based on the old lyx doc.

-- 
Ville M. Vainio - vivainio.googlepages.com
blog=360.yahoo.com/villevainio - g[mail | talk]='vivainio'


More information about the IPython-user mailing list