[Python-checkins] r64327 - in doctools/trunk: CHANGES TODO doc/config.rst sphinx/builder.py sphinx/config.py sphinx/quickstart.py sphinx/templates/genindex-single.html sphinx/templates/genindex-split.html sphinx/templates/genindex.html sphinx/templates/modindex.html
georg.brandl
python-checkins at python.org
Tue Jun 17 11:01:26 CEST 2008
Author: georg.brandl
Date: Tue Jun 17 11:01:26 2008
New Revision: 64327
Log:
Support splitting the HTML index.
Added:
doctools/trunk/sphinx/templates/genindex-single.html (contents, props changed)
doctools/trunk/sphinx/templates/genindex-split.html (contents, props changed)
Modified:
doctools/trunk/CHANGES
doctools/trunk/TODO
doctools/trunk/doc/config.rst
doctools/trunk/sphinx/builder.py
doctools/trunk/sphinx/config.py
doctools/trunk/sphinx/quickstart.py
doctools/trunk/sphinx/templates/genindex.html
doctools/trunk/sphinx/templates/modindex.html
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Tue Jun 17 11:01:26 2008
@@ -25,6 +25,10 @@
- The new config value `html_use_index` can be used to switch index
generation in HTML documents off.
+ - The new config value `html_split_index` can be used to create
+ separate index pages for each letter, to be used when the complete
+ index is too large for one page.
+
- The new config value `html_short_title` can be used to set a
shorter title for the documentation which is then used in the
navigation bar.
Modified: doctools/trunk/TODO
==============================================================================
--- doctools/trunk/TODO (original)
+++ doctools/trunk/TODO Tue Jun 17 11:01:26 2008
@@ -8,7 +8,6 @@
- range and object options for literalinclude
- option for compact module index
- HTML section numbers?
-- split the general index?
- "seealso" links to external examples, see http://svn.python.org/projects/sandbox/trunk/seealso/ and http://effbot.org/zone/idea-seealso.htm
- "often used" combo box in sidebar
- source file cross-references?
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Tue Jun 17 11:01:26 2008
@@ -287,6 +287,13 @@
.. versionadded:: 0.4
+.. confval:: html_split_index
+
+ If true, the index is generated twice: once as a single page with all the
+ entries, and once as one page per starting letter. Default is ``False``.
+
+ .. versionadded:: 0.4
+
.. confval:: html_copy_source
If true, the reST sources are included in the HTML build as
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py (original)
+++ doctools/trunk/sphinx/builder.py Tue Jun 17 11:01:26 2008
@@ -5,7 +5,7 @@
Builder classes for different output formats.
- :copyright: 2007-2008 by Georg Brandl.
+ :copyright: 2007-2008 by Georg Brandl, Sebastian Wiesner.
:license: BSD.
"""
@@ -464,9 +464,19 @@
genindexcontext = dict(
genindexentries = genindex,
genindexcounts = indexcounts,
+ split_index = self.config.html_split_index,
)
self.info(' genindex', nonl=1)
- self.handle_page('genindex', genindexcontext, 'genindex.html')
+
+ if self.config.html_split_index:
+ self.handle_page('genindex', genindexcontext, 'genindex-split.html')
+ self.handle_page('genindex-all', genindexcontext, 'genindex.html')
+ for (key, entries), count in zip(genindex, indexcounts):
+ ctx = {'key': key, 'entries': entries, 'count': count,
+ 'genindexentries': genindex}
+ self.handle_page('genindex-' + key, ctx, 'genindex-single.html')
+ else:
+ self.handle_page('genindex', genindexcontext, 'genindex.html')
# the global module index
@@ -481,6 +491,7 @@
platforms = set()
# sort out collapsable modules
modindexentries = []
+ letters = []
pmn = ''
cg = 0 # collapse group
fl = '' # first letter
@@ -488,8 +499,10 @@
pl = pl and pl.split(', ') or []
platforms.update(pl)
if fl != mn[0].lower() and mn[0] != '_':
+ # heading
modindexentries.append(['', False, 0, False,
mn[0].upper(), '', [], False])
+ letters.append(mn[0].upper())
tn = mn.split('.')[0]
if tn != mn:
# submodule
@@ -510,6 +523,7 @@
modindexcontext = dict(
modindexentries = modindexentries,
platforms = platforms,
+ letters = letters,
)
self.info(' modindex', nonl=1)
self.handle_page('modindex', modindexcontext, 'modindex.html')
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py (original)
+++ doctools/trunk/sphinx/config.py Tue Jun 17 11:01:26 2008
@@ -59,6 +59,7 @@
html_additional_pages = ({}, False),
html_use_modindex = (True, False),
html_use_index = (True, False),
+ html_split_index = (False, False),
html_copy_source = (True, False),
html_use_opensearch = ('', False),
html_file_suffix = (None, False),
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py (original)
+++ doctools/trunk/sphinx/quickstart.py Tue Jun 17 11:01:26 2008
@@ -143,6 +143,9 @@
# If false, no index is generated.
#html_use_index = True
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
# If true, the reST sources are included in the HTML build as _sources/<name>.
#html_copy_source = True
Added: doctools/trunk/sphinx/templates/genindex-single.html
==============================================================================
--- (empty file)
+++ doctools/trunk/sphinx/templates/genindex-single.html Tue Jun 17 11:01:26 2008
@@ -0,0 +1,45 @@
+{% extends "layout.html" %}
+{% set title = 'Index' %}
+{% block body %}
+
+ <h1 id="index">Index – {{ key }}</h1>
+
+<table width="100%" class="indextable"><tr><td width="33%" valign="top">
+<dl>
+{%- set breakat = count // 2 %}
+{%- set numcols = 1 %}
+{%- set numitems = 0 %}
+{% for entryname, (links, subitems) in entries %}
+<dt>{%- if links -%}<a href="{{ links[0] }}">{{ entryname|e }}</a>
+ {%- for link in links[1:] %}, <a href="{{ link }}">[Link]</a>{% endfor -%}
+ {%- else -%}
+{{ entryname|e }}
+ {%- endif -%}</dt>
+ {%- if subitems %}
+ <dd><dl>
+ {%- for subentryname, subentrylinks in subitems %}
+ <dt><a href="{{ subentrylinks[0] }}">{{ subentryname|e }}</a>
+ {%- for link in subentrylinks[1:] %}, <a href="{{ link }}">[Link]</a>{% endfor -%}
+ </dt>
+ {%- endfor %}
+ </dl></dd>
+ {%- endif -%}
+{%- set numitems = numitems + 1 + len(subitems) -%}
+{%- if numcols < 2 and numitems > breakat -%}
+{%- set numcols = numcols+1 -%}
+</dl></td><td width="33%" valign="top"><dl>
+{%- endif -%}
+{%- endfor %}
+</dl></td></tr></table>
+
+{% endblock %}
+
+{% block sidebarrel %}
+ <h4>Index</h4>
+ <p>{% for key, dummy in genindexentries -%}
+ <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
+ {% if not loop.last %}| {% endif %}
+ {%- endfor %}</p>
+
+ <p><a href="{{ pathto('genindex-all') }}"><strong>Full index on one page</strong></a></p>
+{% endblock %}
Added: doctools/trunk/sphinx/templates/genindex-split.html
==============================================================================
--- (empty file)
+++ doctools/trunk/sphinx/templates/genindex-split.html Tue Jun 17 11:01:26 2008
@@ -0,0 +1,29 @@
+{% extends "layout.html" %}
+{% set title = 'Index' %}
+{% block body %}
+
+ <h1 id="index">Index</h1>
+
+ <p>Index pages by letter:</p>
+
+ <p>{% for key, dummy in genindexentries -%}
+ <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
+ {% if not loop.last %}| {% endif %}
+ {%- endfor %}</p>
+
+ <p><a href="{{ pathto('genindex-all') }}"><strong>Full index on one page</strong>
+ (can be huge)</a></p>
+
+{% endblock %}
+
+{% block sidebarrel %}
+{% if split_index %}
+ <h4>Index</h4>
+ <p>{% for key, dummy in genindexentries -%}
+ <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
+ {% if not loop.last %}| {% endif %}
+ {%- endfor %}</p>
+
+ <p><a href="{{ pathto('genindex-all') }}"><strong>Full index on one page</strong></a></p>
+{% endif %}
+{% endblock %}
Modified: doctools/trunk/sphinx/templates/genindex.html
==============================================================================
--- doctools/trunk/sphinx/templates/genindex.html (original)
+++ doctools/trunk/sphinx/templates/genindex.html Tue Jun 17 11:01:26 2008
@@ -42,3 +42,15 @@
{% endfor %}
{% endblock %}
+
+{% block sidebarrel %}
+{% if split_index %}
+ <h4>Index</h4>
+ <p>{% for key, dummy in genindexentries -%}
+ <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
+ {% if not loop.last %}| {% endif %}
+ {%- endfor %}</p>
+
+ <p><a href="{{ pathto('genindex-all') }}"><strong>Full index on one page</strong></a></p>
+{% endif %}
+{% endblock %}
Modified: doctools/trunk/sphinx/templates/modindex.html
==============================================================================
--- doctools/trunk/sphinx/templates/modindex.html (original)
+++ doctools/trunk/sphinx/templates/modindex.html Tue Jun 17 11:01:26 2008
@@ -24,11 +24,16 @@
</form>
{% endif %}
+ {%- for letter in letters %}
+ <a href="#cap-{{ letter }}"><strong>{{ letter }}</strong></a> {% if not loop.last %}| {% endif %}
+ {%- endfor %}
+ <hr/>
+
<table width="100%" class="indextable" cellspacing="0" cellpadding="2">
{%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %}
{%- if not modname -%}
<tr class="pcap"><td></td><td> </td><td></td></tr>
- <tr class="cap"><td></td><td><strong>{{ fname }}</strong></td><td></td></tr>
+ <tr class="cap"><td></td><td><a name="cap-{{ fname }}"><strong>{{ fname }}</strong></a></td><td></td></tr>
{%- else -%}
<tr{% if indent %} class="cg-{{ cgroup }}"{% endif %}>
<td>{% if collapse -%}
More information about the Python-checkins
mailing list