[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

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 &ndash; {{ 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>&nbsp;</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 -%}
