add modindex_common_prefix config value

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.

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

doc/config.rst

@@ -164,6 +164,16 @@ 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
 -------------------
 

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,

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' %

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

sphinx/templates/modindex.html

@@ -18,7 +18,7 @@
    <hr/>
 
    <table width="100%" class="indextable" cellspacing="0" cellpadding="2">
-   {%- 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 -%}
    <tr class="pcap"><td></td><td>&nbsp;</td><td></td></tr>
    <tr class="cap"><td></td><td><a name="cap-{{ fname }}"><strong>{{ fname }}</strong></a></td><td></td></tr>
@@ -30,7 +30,7 @@
          {%- endif %}</td>
      <td>{% if indent %}&nbsp;&nbsp;&nbsp;{% endif %}
      {% if fname %}<a href="{{ fname }}">{% endif -%}
-     <tt class="xref">{{ modname|e }}</tt>
+     <tt class="xref">{{ stripped|e }}{{ modname|e }}</tt>
      {%- if fname %}</a>{% endif %}
    {%- if pform and pform[0] %} <em>({{ pform|join(', ') }})</em>{% endif -%}
    </td><td>{% if dep %}<strong>{{ _('Deprecated')}}:</strong>{% endif %}