[Doc-SIG] [Python-Dev] The docs, reloaded

[Aahz]

On Sat, May 19, 2007, Georg Brandl 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.

Excellent work!  This really proves the power of docutils to handle even
complex documents!  Looks pretty good in Lynx, too.

You probably know these, but I don't see anyone else mentioning these
things that need work:

* http://pydoc.gbrandl.de/modules/index.html
needs to reference
http://pydoc.gbrandl.de/reference/functions.html
and 
http://pydoc.gbrandl.de/reference/stdtypes.html
(I see that you've moved them to the Lang Ref, but it will hurt adoption
of this new format if you don't cross-link with the Lib Ref, where they
currently are.)

* Your version creates only a single page for documenting a module; this
is most notable with docs for modules that used to have multiple pages,
such as ``re``.  Compare
http://pydoc.gbrandl.de/modules/re.html
with
http://docs.python.org/lib/module-re.html
There are advantages to the single-page approach, but you should at least
change it to include a top-of-page ToC.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"Look, it's your affair if you want to play with five people, but don't
go calling it doubles."  --John Cleese anticipates Usenet