[IPython-user] Time for documentation infrastructure overhaul?

Fernando Perez fperez.net@gmail....
Tue Aug 21 12:14:02 CDT 2007


On 8/21/07, Ville M. Vainio <vivainio@gmail.com> wrote:
> I was wondering, would it make sense to make the manual "publically
> editable"? The svn is not really the problem, but the special
> toolchain (lyx etc.) required for it is. I admit I haven't bothered to
> pay the official documentation the attention it deserves, and it has
> been lagging for quite a while.
>
> I remember there was a flamewar or two regarding this on python-dev
> (python documentation is also a pain to maintain), but there are much
> less of us so I think it could be more manageable here :-)
>
> Of course there isn't too much time to invest into this, but since
> apparently TRAC supports reStructuredText, perhaps the documentation
> could be converted to reST and placed in TRAC?
>
> Ideas & suggestions welcome.

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
share of the work for the official python docs was Georg Brandl, he
converted the old Latex-based docs to rest, and set up tools to
generate HTML out of them.

We need this badly because nobody except me touches the manual, and
I've now pretty much stopped updating trunk, since we're well on our
way (thanks to Eric Jones, Gael Varoquaux and a bunch of other people
who helped at Scipy07) towards a proper ipython based on the saw dev
branch.  This means that the docs are only going to get worse.

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.

But it would be great if someone could help us with this part: it's a
good way to help ipython in a critical point, it doesn't require
touching any code, and it can be done at your own pace.

The tasks would be:

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

- Figuring out a nice set of build tools that can be used to
automatically create docs in HTML and PDF from each of these
documents.

- Having a central index page similar to

http://docs.python.org/dev/

that links to the manual, the new_design, and any other docs we may produce.


What I want is for that central index to be the html access point to
all the docs, but with each main doc being usable as a standalone
entity with a PDF version (many people like to print the PDF manual
for offline reading).

- Finding out the necessary steps to have all of this accessible from
the main moin wiki.  We'd have something like

doc/stable  -> access to all the docs (html/pdf) from the last release
doc/dev -> same thing from svn, nightly updated via cron job.

I want to keep as much as we can on the main moin wiki to reduce
potential confusion to users, with the Trac wiki being used very
little, and really only for coordinating things amongst developers.

Even users who track SVN daily should find all they need on the main wiki.

This is to reduce potential confusion and also to reduce our working
load.  We need the docs on the main wiki anyway, so I don't want to
have to figure out how to do all of it both for Moin and for Trac.


Any volunteers?  If anyone is willing to help with this, I've exported
the lyx files to .tex here:

http://ipython.scipy.org/misc/doc_tex/

That way you don't need to install lyx at all, but can start from the
tex sources, which is what I imagine Georg's tools accept as an input.

Cheers,

f


More information about the IPython-user mailing list