diff --git a/CHANGES b/CHANGES
index 47cfa672b..6e7d59343 100644
--- a/CHANGES
+++ b/CHANGES
@@ -61,6 +61,9 @@ New features added
- The default value for ``htmlhelp_basename`` is now the project
title, cleaned up as a filename.
+ - The new ``modindex_common_prefix`` config value can be used to
+ ignore certain package names for module index sorting.
+
* Builders:
- New builder for Qt help collections, by Antonio Valentino.
diff --git a/doc/conf.py b/doc/conf.py
index 709d6f750..87afc6592 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -68,6 +68,9 @@ show_authors = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'friendly'
+# A list of ignored prefixes names for module index sorting.
+modindex_common_prefix = ['sphinx.']
+
# Options for HTML output
# -----------------------
diff --git a/doc/config.rst b/doc/config.rst
index dd25cf223..ad14d1ed8 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -76,7 +76,7 @@ General configuration
.. versionadded:: 0.5
Previously, Sphinx accepted only UTF-8 encoded sources.
-
+
.. confval:: master_doc
The document name of the "master" document, that is, the document that
@@ -164,9 +164,19 @@ General configuration
.. versionadded:: 0.5
+.. confval:: modindex_common_prefix
+
+ A list of prefixes that are ignored for sorting the module index (e.g.,
+ if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, not
+ ``F``). This can be handy if you document a project that consists of a single
+ package. Works only for the HTML builder currently. Default is ``[]``.
+
+ .. versionadded:: 0.6
+
+
Project information
-------------------
-
+
.. confval:: project
The documented project's name.
@@ -233,7 +243,7 @@ Project information
:ref:`code-examples` for more details.
.. versionadded:: 0.5
-
+
.. confval:: pygments_style
The style name to use for Pygments highlighting of source code. Default is
@@ -341,7 +351,7 @@ that use Sphinx' HTMLWriter class.
.. versionadded:: 0.6
Previously, this was always activated.
-
+
.. confval:: html_sidebars
Custom sidebar templates, must be a dictionary that maps document names to
@@ -439,7 +449,7 @@ that use Sphinx' HTMLWriter class.
support different web server setups).
.. versionadded:: 0.6
-
+
.. confval:: html_translator_class
A string with the fully-qualified name of a HTML Translator class, that is, a
@@ -527,7 +537,7 @@ These options influence LaTeX output.
avoid interpretation as escape sequences.
* Keys that you may want to override include:
-
+
``'papersize'``
Paper size option of the document class (``'a4paper'`` or
``'letterpaper'``), default ``'letterpaper'``.
@@ -551,9 +561,9 @@ These options influence LaTeX output.
Additional preamble content, default empty.
``'footer'```
Additional footer content (before the indices), default empty.
-
+
* Keys that don't need be overridden unless in special cases are:
-
+
``'inputenc'``
"inputenc" package inclusion, default
``'\\usepackage[utf8]{inputenc}'``.
@@ -570,9 +580,9 @@ These options influence LaTeX output.
"printindex" call, the last thing in the file, default
``'\\printindex'``. Override if you want to generate the index
differently or append some content after the index.
-
+
* Keys that are set by other options and therefore should not be overridden are:
-
+
``'docclass'``
``'classoptions'``
``'title'``
@@ -585,7 +595,7 @@ These options influence LaTeX output.
``'makemodindex'``
``'shorthandoff'``
``'printmodindex'``
-
+
.. confval:: latex_preamble
Additional LaTeX markup for the preamble.
diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index 91682aa20..20223ee0d 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -292,11 +292,24 @@ class StandaloneHTMLBuilder(Builder):
for mn, (fn, sy, pl, dep) in modules:
pl = pl and pl.split(', ') or []
platforms.update(pl)
+
+ ignore = self.env.config['modindex_common_prefix']
+ ignore = sorted(ignore, key=len, reverse=True)
+ for i in ignore:
+ if mn.startswith(i):
+ mn = mn[len(i):]
+ stripped = i
+ break
+ else:
+ stripped = ''
+
if fl != mn[0].lower() and mn[0] != '_':
# heading
- modindexentries.append(['', False, 0, False,
- mn[0].upper(), '', [], False])
- letters.append(mn[0].upper())
+ letter = mn[0].upper()
+ if letter not in letters:
+ modindexentries.append(['', False, 0, False,
+ letter, '', [], False, ''])
+ letters.append(letter)
tn = mn.split('.')[0]
if tn != mn:
# submodule
@@ -307,11 +320,13 @@ class StandaloneHTMLBuilder(Builder):
elif not pmn.startswith(tn):
# submodule without parent in list, add dummy entry
cg += 1
- modindexentries.append([tn, True, cg, False, '', '', [], False])
+ modindexentries.append([tn, True, cg, False, '', '',
+ [], False, stripped])
else:
num_toplevels += 1
cg += 1
- modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep])
+ modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl,
+ dep, stripped])
pmn = mn
fl = mn[0].lower()
platforms = sorted(platforms)
@@ -321,6 +336,19 @@ class StandaloneHTMLBuilder(Builder):
# number of submodules
collapse = len(modules) - num_toplevels < num_toplevels
+ # As some parts of the module names may have been stripped, those
+ # names have changed, thus it is necessary to sort the entries.
+ if ignore:
+ def sorthelper(entry):
+ name = entry[0]
+ if name == '':
+ # heading
+ name = entry[4]
+ return name.lower()
+
+ modindexentries.sort(key=sorthelper)
+ letters.sort()
+
modindexcontext = dict(
modindexentries = modindexentries,
platforms = platforms,
diff --git a/sphinx/config.py b/sphinx/config.py
index 428c0bf40..2f8ee1e57 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -51,6 +51,7 @@ class Config(object):
templates_path = ([], False),
template_bridge = (None, False),
keep_warnings = (False, True),
+ modindex_common_prefix = ([], False),
# HTML options
html_title = (lambda self: '%s v%s documentation' %
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index 67ab62731..343ea0cf8 100644
--- a/sphinx/quickstart.py
+++ b/sphinx/quickstart.py
@@ -111,6 +111,9 @@ exclude_trees = [%(exclude_trees)s]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
# Options for HTML output
# -----------------------
diff --git a/sphinx/templates/modindex.html b/sphinx/templates/modindex.html
index 6e33e55c2..0392edc80 100644
--- a/sphinx/templates/modindex.html
+++ b/sphinx/templates/modindex.html
@@ -18,7 +18,7 @@
- {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %}
+ {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep, stripped in modindexentries %}
{%- if not modname -%}
| | |
| {{ fname }} | |
@@ -30,7 +30,7 @@
{%- endif %}
{% if indent %} {% endif %}
{% if fname %}{% endif -%}
- {{ modname|e }}
+ {{ stripped|e }}{{ modname|e }}
{%- if fname %}{% endif %}
{%- if pform and pform[0] %} ({{ pform|join(', ') }}){% endif -%}
| {% if dep %}{{ _('Deprecated')}}:{% endif %}
|