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

[Alexandre Vassalotti]

On 8/17/07, Georg Brandl <g.brandl at gmx.net> wrote:
> 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/".

Ah, I didn't notice that index included all the documents. That
explains the huge size increase. However, would it be possible to keep
the indexes separated? I noticed that I find I want more quickly when
the indexes are separated.

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

I disabled CSS-support (with View->Page Style->No Style), but it
didn't affect the initial rendering speed. However, scrolling was
*much* faster without CSS.

-- Alexandre