[Python-3000] [Python-Dev] Documentation switch imminent

[Georg Brandl]

Alexandre Vassalotti schrieb:
> On 8/16/07, Neal Norwitz <nnorwitz at gmail.com> wrote:
>> On 8/15/07, Georg Brandl <g.brandl at gmx.net> wrote:
>> > Okay, I made the switch.  I tagged the state of both Python branches
>> > before the switch as tags/py{26,3k}-before-rstdocs/.
>>
>> http://docs.python.org/dev/
>> http://docs.python.org/dev/3.0/
>>
> 
> Is it just me, or the markup of the new docs is quite heavy?

Docutils markup tends to be a bit verbose, yes, but the index is not
even generated by them.

> alex% wget -q -O- http://docs.python.org/api/genindex.html | wc -c
> 77868
> alex% wget -q -O- http://docs.python.org/dev/3.0/genindex.html | wc -c
> 918359

The new index includes all documents (api, lib, ref, ...), so the ratio
is more like 678000 : 950000 (using 2.6 here), and the difference can be
explained quite easily because (a) sphinx uses different anchor names
("mailbox.Mailbox.__contains__" vs "l2h-849") and the hrefs have to
include subdirs like "reference/".

I've now removed leading spaces in the index output, and the character
count is down to 850000.

> Firefox, on my fairly recent machine, takes ~5 seconds rendering the
> index of the new docs from disk, compared to a fraction of a second
> for the old one.

But you're right that rendering is slow there.  It may be caused by the
more complicated CSS... perhaps the index should be split up in several
pages.

Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.