From 6b5f4f198a631ab33ac7b4a1e4d7e17ed54743ce Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 17 Jun 2008 09:01:26 +0000 Subject: [PATCH] Support splitting the HTML index. --- CHANGES | 4 +++ TODO | 1 - doc/config.rst | 7 +++++ sphinx/builder.py | 18 +++++++++-- sphinx/config.py | 1 + sphinx/quickstart.py | 3 ++ sphinx/templates/genindex-single.html | 45 +++++++++++++++++++++++++++ sphinx/templates/genindex-split.html | 29 +++++++++++++++++ sphinx/templates/genindex.html | 12 +++++++ sphinx/templates/modindex.html | 7 ++++- 10 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 sphinx/templates/genindex-single.html create mode 100644 sphinx/templates/genindex-split.html diff --git a/CHANGES b/CHANGES index ee1fc7e7f..0825a89c8 100644 --- a/CHANGES +++ b/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. diff --git a/TODO b/TODO index 15d1c5c3a..910563bcd 100644 --- a/TODO +++ b/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? diff --git a/doc/config.rst b/doc/config.rst index baf2b7584..2cbe850c1 100644 --- a/doc/config.rst +++ b/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 diff --git a/sphinx/builder.py b/sphinx/builder.py index b868841d4..34e829265 100644 --- a/sphinx/builder.py +++ b/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') diff --git a/sphinx/config.py b/sphinx/config.py index fb5a47e80..fde87173b 100644 --- a/sphinx/config.py +++ b/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), diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 17cb9f599..2df7fabbb 100644 --- a/sphinx/quickstart.py +++ b/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/. #html_copy_source = True diff --git a/sphinx/templates/genindex-single.html b/sphinx/templates/genindex-single.html new file mode 100644 index 000000000..6caa4b4ce --- /dev/null +++ b/sphinx/templates/genindex-single.html @@ -0,0 +1,45 @@ +{% extends "layout.html" %} +{% set title = 'Index' %} +{% block body %} + +

Index – {{ key }}

+ +
+
+{%- set breakat = count // 2 %} +{%- set numcols = 1 %} +{%- set numitems = 0 %} +{% for entryname, (links, subitems) in entries %} +
{%- if links -%}{{ entryname|e }} + {%- for link in links[1:] %}, [Link]{% endfor -%} + {%- else -%} +{{ entryname|e }} + {%- endif -%}
+ {%- if subitems %} +
+ {%- for subentryname, subentrylinks in subitems %} +
{{ subentryname|e }} + {%- for link in subentrylinks[1:] %}, [Link]{% endfor -%} +
+ {%- endfor %} +
+ {%- endif -%} +{%- set numitems = numitems + 1 + len(subitems) -%} +{%- if numcols < 2 and numitems > breakat -%} +{%- set numcols = numcols+1 -%} +
+{%- endif -%} +{%- endfor %} +
+ +{% endblock %} + +{% block sidebarrel %} +

Index

+

{% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

+ +

Full index on one page

+{% endblock %} diff --git a/sphinx/templates/genindex-split.html b/sphinx/templates/genindex-split.html new file mode 100644 index 000000000..957fd4c31 --- /dev/null +++ b/sphinx/templates/genindex-split.html @@ -0,0 +1,29 @@ +{% extends "layout.html" %} +{% set title = 'Index' %} +{% block body %} + +

Index

+ +

Index pages by letter:

+ +

{% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

+ +

Full index on one page + (can be huge)

+ +{% endblock %} + +{% block sidebarrel %} +{% if split_index %} +

Index

+

{% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

+ +

Full index on one page

+{% endif %} +{% endblock %} diff --git a/sphinx/templates/genindex.html b/sphinx/templates/genindex.html index f33769272..38ac13966 100644 --- a/sphinx/templates/genindex.html +++ b/sphinx/templates/genindex.html @@ -42,3 +42,15 @@ {% endfor %} {% endblock %} + +{% block sidebarrel %} +{% if split_index %} +

Index

+

{% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

+ +

Full index on one page

+{% endif %} +{% endblock %} diff --git a/sphinx/templates/modindex.html b/sphinx/templates/modindex.html index 3cd79e949..1afc16506 100644 --- a/sphinx/templates/modindex.html +++ b/sphinx/templates/modindex.html @@ -24,11 +24,16 @@ {% endif %} + {%- for letter in letters %} + {{ letter }} {% if not loop.last %}| {% endif %} + {%- endfor %} +
+ {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %} {%- if not modname -%} - + {%- else -%}
 
{{ fname }}
{{ fname }}
{% if collapse -%}