[Doc-SIG] [Python-Dev] The docs, reloaded
Aahz
aahz at pythoncraft.com
Mon May 21 00:42:21 CEST 2007
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
More information about the Doc-SIG
mailing list