Support splitting the HTML index.

CHANGES

@@ -25,6 +25,10 @@ New features added
   - 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.

TODO

@@ -8,7 +8,6 @@ Sphinx
 - 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?

doc/config.rst

@@ -287,6 +287,13 @@ that use Sphinx' HTMLWriter class.
 
    .. 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

sphinx/builder.py

@@ -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 @@ class StandaloneHTMLBuilder(Builder):
             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 @@ class StandaloneHTMLBuilder(Builder):
             platforms = set()
             # sort out collapsable modules
             modindexentries = []
+            letters = []
             pmn = ''
             cg = 0 # collapse group
             fl = '' # first letter
@@ -488,8 +499,10 @@ class StandaloneHTMLBuilder(Builder):
                 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 @@ class StandaloneHTMLBuilder(Builder):
             modindexcontext = dict(
                 modindexentries = modindexentries,
                 platforms = platforms,
+                letters = letters,
             )
             self.info(' modindex', nonl=1)
             self.handle_page('modindex', modindexcontext, 'modindex.html')

sphinx/config.py

@@ -59,6 +59,7 @@ class Config(object):
         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),

sphinx/quickstart.py

@@ -143,6 +143,9 @@ html_last_updated_fmt = '%%b %%d, %%Y'
 # 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
 

sphinx/templates/genindex-single.html

@@ -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 %}

sphinx/templates/genindex-split.html

@@ -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 %}

sphinx/templates/genindex.html

@@ -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 %}

sphinx/templates/modindex.html

@@ -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 -%}