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

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

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,
+                    letter = mn[0].upper()
-                                            mn[0].upper(), '', [], False])
+                    if letter not in letters:
-                    letters.append(mn[0].upper())
+                        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 %}