Commits

Anonymous committed a4e7d7a

Support splitting the HTML index.

  • Participants
  • Parent commits 81e1a65

Comments (0)

Files changed (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.
 - 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?

File doc/config.rst

 
    .. 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

File sphinx/builder.py

 
     Builder classes for different output formats.
 
-    :copyright: 2007-2008 by Georg Brandl.
+    :copyright: 2007-2008 by Georg Brandl, Sebastian Wiesner.
     :license: BSD.
 """
 
             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
 
             platforms = set()
             # sort out collapsable modules
             modindexentries = []
+            letters = []
             pmn = ''
             cg = 0 # collapse group
             fl = '' # first letter
                 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
             modindexcontext = dict(
                 modindexentries = modindexentries,
                 platforms = platforms,
+                letters = letters,
             )
             self.info(' modindex', nonl=1)
             self.handle_page('modindex', modindexcontext, 'modindex.html')

File sphinx/config.py

         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),

File sphinx/quickstart.py

 # 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
 

File sphinx/templates/genindex-single.html

+{% 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 %}

File sphinx/templates/genindex-split.html

+{% 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 %}

File sphinx/templates/genindex.html

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

File sphinx/templates/modindex.html

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