-
Notifications
You must be signed in to change notification settings - Fork 35
/
versionwarning.py
70 lines (51 loc) · 2.16 KB
/
versionwarning.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
# -*- coding: utf-8 -*-
"""
Add the ability to specify the version for a specific page.
This allows you to put metadata at the top of your document::
:version: 2.3
This version should be the version of the project that this page or API targets.
If you configure ``versionwarning-node`` to True (default),
then it will generate an in-page warning for out of date versions.
If you configure ``versionwarning-console`` to True (default),
then it will output a warning on the console.
"""
from collections import defaultdict
from sphinx.util.console import red, bold
from docutils import nodes
try:
# Available from Sphinx 1.6
from sphinx.util.logging import getLogger
except ImportError:
from logging import getLogger
log = getLogger(__name__)
def process_meta(app, doctree, fromdocname):
env = app.builder.env
env.page_to_version = defaultdict(set)
env.version_to_page = defaultdict(set)
# index metadata
for pagename, metadata in env.metadata.iteritems():
if 'version' in metadata:
version = metadata['version']
env.page_to_version[pagename] = version
env.version_to_page[version].add(pagename)
if fromdocname == pagename:
# Alert on outdated version
current_version = env.config['version']
if version != current_version:
text = 'This page documents version {old}. The latest version is {new}'.format(
old=version,
new=current_version,
)
if app.config['versionwarning-node']:
prose = nodes.paragraph(text, text)
warning = nodes.warning(prose, prose)
doctree.insert(0, warning)
if app.config['versionwarning-console']:
log.warning(bold('[Version Warning: %s] ' % pagename) + red(text))
def setup(app):
app.connect('doctree-resolved', process_meta)
app.add_config_value('versionwarning-node', True, 'html')
app.add_config_value('versionwarning-console', True, 'html')
return {
'parallel_read_safe': True,
}