[Python-Dev] The docs, reloaded

[Nick Craig-Wood]

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