mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Add a way to mark deprecated modules, and show this information in the module index.
Also, generate a useful "title" attribute for module crossreferences.
This commit is contained in:
Georg Brandl
parent
11cab438b8
commit
d302c52646
@ -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))
|
||||
for (mn, (fn, sy, pl)) in self.env.modules.iteritems()),
|
||||
'#module-' + mn, sy, pl, dep))
|
||||
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)
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
|
||||
@ -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):
|
||||
self.modules[modname] = (self.filename, synopsis, platform)
|
||||
def note_module(self, modname, synopsis, platform, deprecated):
|
||||
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, '')
|
||||
|
||||
@ -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> </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>
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user