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

Nick Craig-Wood nick at craig-wood.com
Mon May 21 11:43:41 CEST 2007

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?

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

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

-- Nick Craig-Wood <nick at craig-wood.com> -- http://www.craig-wood.com/nick

More information about the Python-Dev mailing list