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

[Georg Brandl]

Aahz schrieb:
> 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.

Thanks! The docutils really do a good job there.

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

I've moved these sections as a suggestion; for me it always felt more natural
this way. However, I intend to ask for opinions there; if the consensus is
that the current order is better, it can be reinstated with a change of one or
two lines in the converter.

But you're right: A link for those being used to the old order is needed
in any case.

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

The TOC is there, in the left sidebar.

I agree that multiple pages can be much more readable for large chapters.
That is one thing that would have to be decide after the conversion, and
do manually (which isn't really hard).

cheers,
Georg