Add a way to mark deprecated modules, and show this information in the module index.

Also, generate a useful "title" attribute for module crossreferences.

sphinx/builder.py

@@ -393,8 +393,8 @@ class StandaloneHTMLBuilder(Builder):
 
         # the sorted list of all modules, for the global module index
         modules = sorted(((mn, (self.get_relative_uri('modindex.rst', fn) +
-                                '#module-' + mn, sy, pl))
+                                '#module-' + mn, sy, pl, dep))
-                          for (mn, (fn, sy, pl)) in self.env.modules.iteritems()),
+                          for (mn, (fn, sy, pl, dep)) in self.env.modules.iteritems()),
                          key=lambda x: x[0].lower())
         # collect all platforms
         platforms = set()
@@ -403,11 +403,11 @@ class StandaloneHTMLBuilder(Builder):
         pmn = ''
         cg = 0 # collapse group
         fl = '' # first letter
-        for mn, (fn, sy, pl) in modules:
+        for mn, (fn, sy, pl, dep) in modules:
             pl = pl.split(', ') if pl else []
             platforms.update(pl)
             if fl != mn[0].lower() and mn[0] != '_':
-                modindexentries.append(['', False, 0, False, mn[0].upper(), '', []])
+                modindexentries.append(['', False, 0, False, mn[0].upper(), '', [], False])
             tn = mn.partition('.')[0]
             if tn != mn:
                 # submodule
@@ -417,10 +417,10 @@ class StandaloneHTMLBuilder(Builder):
                 elif not pmn.startswith(tn):
                     # submodule without parent in list, add dummy entry
                     cg += 1
-                    modindexentries.append([tn, True, cg, False, '', '', []])
+                    modindexentries.append([tn, True, cg, False, '', '', [], False])
             else:
                 cg += 1
-            modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl])
+            modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep])
             pmn = mn
             fl = mn[0].lower()
         platforms = sorted(platforms)

sphinx/directives.py

@@ -472,7 +472,9 @@ def module_directive(name, arguments, options, content, lineno,
     env = state.document.settings.env
     modname = arguments[0].strip()
     env.currmodule = modname
-    env.note_module(modname, options.get('synopsis', ''), options.get('platform', ''))
+    env.note_module(modname, options.get('synopsis', ''),
+                    options.get('platform', ''),
+                    'deprecated' in options)
     ret = []
     targetnode = nodes.target('', '', ids=['module-' + modname])
     state.document.note_explicit_target(targetnode)
@@ -489,7 +491,8 @@ def module_directive(name, arguments, options, content, lineno,
 
 module_directive.arguments = (1, 0, 0)
 module_directive.options = {'platform': lambda x: x,
-                            'synopsis': lambda x: x}
+                            'synopsis': lambda x: x,
+                            'deprecated': directives.flag}
 directives.register_directive('module', module_directive)
 
 

sphinx/environment.py

@@ -52,7 +52,7 @@ default_settings = {
 
 # This is increased every time a new environment attribute is added
 # to properly invalidate pickle files.
-ENV_VERSION = 9
+ENV_VERSION = 10
 
 
 def walk_depth(node, depth, maxdepth):
@@ -203,7 +203,7 @@ class BuildEnvironment:
         # X-ref target inventory
         self.descrefs = {}          # fullname -> filename, desctype
         self.filemodules = {}       # filename -> [modules]
-        self.modules = {}           # modname -> filename, synopsis, platform
+        self.modules = {}           # modname -> filename, synopsis, platform, deprecated
         self.tokens = {}            # tokenname -> filename
         self.labels = {}            # labelname -> filename, labelid
 
@@ -238,7 +238,7 @@ class BuildEnvironment:
                 if fn == filename:
                     del self.descrefs[fullname]
             self.filemodules.pop(filename, None)
-            for modname, (fn, _, _) in self.modules.items():
+            for modname, (fn, _, _, _) in self.modules.items():
                 if fn == filename:
                     del self.modules[modname]
             for tokenname, fn in self.tokens.items():
@@ -490,8 +490,8 @@ class BuildEnvironment:
                    'in %s and %s' % (self.descrefs[fullname][0], self.filename))
         self.descrefs[fullname] = (self.filename, desctype)
 
-    def note_module(self, modname, synopsis, platform):
+    def note_module(self, modname, synopsis, platform, deprecated):
-        self.modules[modname] = (self.filename, synopsis, platform)
+        self.modules[modname] = (self.filename, synopsis, platform, deprecated)
         self.filemodules.setdefault(self.filename, []).append(modname)
 
     def note_token(self, tokenname):
@@ -605,7 +605,8 @@ class BuildEnvironment:
                             docfilename, filename) + '#grammar-token-' + target
                     newnode.append(contnode)
             elif typ == 'mod':
-                filename, synopsis, platform = self.modules.get(target, ('','',''))
+                filename, synopsis, platform, deprecated = \
+                    self.modules.get(target, ('','',''))
                 # just link to an anchor if there are multiple modules in one file
                 # because the anchor is generally below the heading which is ugly
                 # but can't be helped easily
@@ -619,6 +620,9 @@ class BuildEnvironment:
                     newnode = nodes.reference('', '')
                     newnode['refuri'] = (
                         builder.get_relative_uri(docfilename, filename) + anchor)
+                    newnode['reftitle'] = '%s%s%s' % (
+                        ('(%s) ' % platform if platform else ''),
+                        synopsis, (' (deprecated)' if deprecated else ''))
                     newnode.append(contnode)
             else:
                 searchorder = 1 if node.hasattr('refspecific') else 0
@@ -803,7 +807,7 @@ class BuildEnvironment:
         """
 
         if keyword in self.modules:
-            filename, title, system = self.modules[keyword]
+            filename, title, system, deprecated = self.modules[keyword]
             return 'module', filename, 'module-' + keyword
         if keyword in self.descrefs:
             filename, ref_type = self.descrefs[keyword]
@@ -827,7 +831,7 @@ class BuildEnvironment:
         s.set_seq2(keyword.lower())
 
         def possibilities():
-            for title, (fn, desc, _) in self.modules.iteritems():
+            for title, (fn, desc, _, _) in self.modules.iteritems():
                 yield ('module', fn, 'module-'+title, desc)
             for title, (fn, desctype) in self.descrefs.iteritems():
                 yield (desctype, fn, title, '')

sphinx/templates/modindex.html

@@ -25,7 +25,7 @@
 {% endif %}
 
    <table width="100%" class="indextable" cellspacing="0" cellpadding="2">
-   {%- for modname, collapse, cgroup, indent, fname, synops, pform in modindexentries %}
+   {%- 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>
@@ -40,7 +40,8 @@
      <tt class="xref">{{ modname|e }}</tt>
      {%- if fname %}</a>{% endif %}
    {%- if pform[0] %} <em>({{ pform|join(', ') }})</em>{% endif -%}
-   </td><td><em>{{ synops|e }}</em></td></tr>
+   </td><td>{% if dep %}<strong>Deprecated:</strong>{% endif %}
+     <em>{{ synops|e }}</em></td></tr>
    {%- endif -%}
    {% endfor %}
    </table>

sphinx/writer.py

@@ -112,6 +112,17 @@ class HTMLTranslator(BaseTranslator):
     def depart_versionmodified(self, node):
         self.body.append('</p>\n')
 
+    # overwritten
+    def visit_reference(self, node):
+        BaseTranslator.visit_reference(self, node)
+        if node.hasattr('reftitle'):
+            # ugly hack to add a title attribute
+            starttag = self.body[-1]
+            if not starttag.startswith('<a '):
+                return
+            self.body[-1] = '<a title="%s"' % self.attval(node['reftitle']) + \
+                            starttag[2:]
+
     # overwritten -- we don't want source comments to show up in the HTML
     def visit_comment(self, node):
         raise nodes.SkipNode