[Python-Dev] The docs, reloaded

[Georg Brandl]

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