classification
Title: sphinx - table of contents doesn't render correctly (html)
Type: behavior Stage:
Components: Documentation tools (Sphinx) Versions: Python 3.0, Python 2.6
process
Status: closed Resolution: duplicate
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, grflanagan, wplappert
Priority: normal Keywords:

Created on 2008-06-25 20:36 by grflanagan, last changed 2008-11-04 20:51 by georg.brandl. This issue is now closed.

Messages (3)
msg68756 - (view) Author: Gerard M. Flanagan (grflanagan) Date: 2008-06-25 20:36
A TOC tree should render in HTML as a single 'ul', but in certain
circumstances it appears as multiple ul's.

You can see the effect here:

    http://docs.python.org/dev/c-api/index.html

and in fact in the Sphinx documentation itself:

    http://sphinx.pocoo.org/contents.html

the 'toctree' here is not an individual entity but a vertical series of
ul's, each of which has a *single* item (li). You may be able to see the
slightly increased space between the ul's which would not be present if
these were all the children of a single parent.

This should be changed so that pages have a unique 'toc' element because:

- it would be easier for css and javascript to manipulate
- there may be accessibility issues (eg. non-visual readers may not 
identify the toc as a single sequence of alternatives)

The reason for the current behaviour can be found in the method
'resolve_toctree' of class sphinx.environment.BuildEnvironment, line 863::

      newnode = addnodes.compact_paragraph('', '', *tocentries)

`tocentries` is a list of `toctrees` [<toctree>, <toctree>,..] each of
which will end up as a ul, while a compact_paragraph has no html
representation; hence the observed effect.

One way to fix this is to replace the above line with the following::

        newnode = nodes.bullet_list()
        for entry in tocentries:
            for item in entry.children:
                assert isinstance(item, nodes.list_item)
                newnode.append(item)

(and you can also take the opportunity here to add a unique id::

        newnode['ids'].append('toc')
)

Note that this new code is a noop if `tocentries` only has one element,
at least as far as html is concerned.
msg69068 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-07-01 20:34
This is already on my to-do list. Thanks for raising it as an issue
though, I won't forget it so easily this way :)
msg75508 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-11-04 20:51
Now tracked in
http://www.bitbucket.org/birkenfeld/sphinx/issue/6/fix-html-generation-for-tocs.
History
Date User Action Args
2008-11-04 20:51:13georg.brandlsetstatus: open -> closed
resolution: duplicate
messages: + msg75508
2008-10-22 20:40:30wplappertsetnosy: + wplappert
2008-07-01 20:34:39georg.brandlsetmessages: + msg69068
2008-06-25 20:36:27grflanagancreate