New submission from Gerard M. Flanagan <[EMAIL PROTECTED]>:
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.
----------
assignee: georg.brandl
components: Documentation tools (Sphinx)
messages: 68756
nosy: georg.brandl, grflanagan
severity: normal
status: open
title: sphinx - table of contents doesn't render correctly (html)
type: behavior
versions: Python 2.6, Python 3.0
_______________________________________
Python tracker <[EMAIL PROTECTED]>
<http://bugs.python.org/issue3203>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
