[Python-Dev] The docs, reloaded (original) (raw)

Georg Brandl g.brandl at gmx.net
Mon May 21 21:01:38 CEST 2007

Nick Craig-Wood schrieb:

Georg Brandl <g.brandl at gmx.net> wrote:

over the last few weeks I've hacked on a new approach to Python's documentation. As Python already has an excellent documentation framework, the docutils, with a readable yet extendable markup format, reST, I thought that it should be possible to use those instead of the current LaTeX->latex2html toolchain. Good idea! Latex is a barrier for contribution to the docs. I imagine most people would be much better at contributing to the docs in reST. (Me included: I learnt latex at university a couple of decades ago and have now forgotten it completely!)

- a "quick-dispatch" function: e.g., docs.python.org/q?os.path.split would redirect you to the matching location. Being a seasoned unix user, I tend to reach for pydoc as my first stab at finding some documentation rather than (after excavating the mouse from under a pile of paper) use a web browser. If you've ever used pydoc you'll know it reads docstrings and for some modules they are great and for others they are sorely lacking. If pydoc could show all this documentation as well I'd be very happy! Maybe your quick dispatch feature could be added to pydoc too?

It is my intention to work together with Ron Adam to make the pydoc <-> documentation integration as seamless as possible.

Concluding, a small caveat: The conversion/build tools are, of course, not complete yet. There are a number of XXX comments in the text, most of them indicate that the converter could not handle a situation -- that would have to be corrected once after conversion is done. It is missing conversion of ``comment'' at the moment as I'm sure you know...

Sorry, what did you mean?

You will need to make your conversion perfect before you convince the people who wrote most of that documentation I suspect!

It already is as good as it gets, barring a few bugs here and there. Which I'd like to hear about, when you find them!

cheers, Georg

More information about the Python-Dev mailing list