]>
Commit | Line | Data |
---|---|---|
638585f7 GKH |
1 | From 096ea522e84ea68f8e6c41e5e7294731a81e29bc Mon Sep 17 00:00:00 2001 |
2 | From: Jonathan Corbet <corbet@lwn.net> | |
3 | Date: Tue, 21 May 2019 14:23:43 -0600 | |
4 | Subject: doc: Cope with Sphinx logging deprecations | |
5 | ||
6 | From: Jonathan Corbet <corbet@lwn.net> | |
7 | ||
8 | commit 096ea522e84ea68f8e6c41e5e7294731a81e29bc upstream. | |
9 | ||
10 | Recent versions of sphinx will emit messages like: | |
11 | ||
12 | Documentation/sphinx/kerneldoc.py:103: | |
13 | RemovedInSphinx20Warning: app.warning() is now deprecated. | |
14 | Use sphinx.util.logging instead. | |
15 | ||
16 | Switch to sphinx.util.logging to make this unsightly message go away. | |
17 | Alas, that interface was only added in version 1.6, so we have to add a | |
18 | version check to keep things working with older sphinxes. | |
19 | ||
20 | Cc: stable@vger.kernel.org | |
21 | Signed-off-by: Jonathan Corbet <corbet@lwn.net> | |
22 | Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> | |
23 | ||
24 | --- | |
25 | Documentation/sphinx/kerneldoc.py | 12 +++++++---- | |
26 | Documentation/sphinx/kernellog.py | 28 ++++++++++++++++++++++++++ | |
27 | Documentation/sphinx/kfigure.py | 40 +++++++++++++++++++++----------------- | |
28 | 3 files changed, 59 insertions(+), 21 deletions(-) | |
29 | ||
30 | --- a/Documentation/sphinx/kerneldoc.py | |
31 | +++ b/Documentation/sphinx/kerneldoc.py | |
32 | @@ -49,6 +49,8 @@ if Use_SSI: | |
33 | else: | |
34 | from sphinx.ext.autodoc import AutodocReporter | |
35 | ||
36 | +import kernellog | |
37 | + | |
38 | __version__ = '1.0' | |
39 | ||
40 | class KernelDocDirective(Directive): | |
41 | @@ -100,7 +102,8 @@ class KernelDocDirective(Directive): | |
42 | cmd += [filename] | |
43 | ||
44 | try: | |
45 | - env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) | |
46 | + kernellog.verbose(env.app, | |
47 | + 'calling kernel-doc \'%s\'' % (" ".join(cmd))) | |
48 | ||
49 | p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) | |
50 | out, err = p.communicate() | |
51 | @@ -110,7 +113,8 @@ class KernelDocDirective(Directive): | |
52 | if p.returncode != 0: | |
53 | sys.stderr.write(err) | |
54 | ||
55 | - env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) | |
56 | + kernellog.warn(env.app, | |
57 | + 'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) | |
58 | return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] | |
59 | elif env.config.kerneldoc_verbosity > 0: | |
60 | sys.stderr.write(err) | |
61 | @@ -136,8 +140,8 @@ class KernelDocDirective(Directive): | |
62 | return node.children | |
63 | ||
64 | except Exception as e: # pylint: disable=W0703 | |
65 | - env.app.warn('kernel-doc \'%s\' processing failed with: %s' % | |
66 | - (" ".join(cmd), str(e))) | |
67 | + kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' % | |
68 | + (" ".join(cmd), str(e))) | |
69 | return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] | |
70 | ||
71 | def do_parse(self, result, node): | |
72 | --- /dev/null | |
73 | +++ b/Documentation/sphinx/kernellog.py | |
74 | @@ -0,0 +1,28 @@ | |
75 | +# SPDX-License-Identifier: GPL-2.0 | |
76 | +# | |
77 | +# Sphinx has deprecated its older logging interface, but the replacement | |
78 | +# only goes back to 1.6. So here's a wrapper layer to keep around for | |
79 | +# as long as we support 1.4. | |
80 | +# | |
81 | +import sphinx | |
82 | + | |
83 | +if sphinx.__version__[:3] >= '1.6': | |
84 | + UseLogging = True | |
85 | + from sphinx.util import logging | |
86 | + logger = logging.getLogger('kerneldoc') | |
87 | +else: | |
88 | + UseLogging = False | |
89 | + | |
90 | +def warn(app, message): | |
91 | + if UseLogging: | |
92 | + logger.warning(message) | |
93 | + else: | |
94 | + app.warn(message) | |
95 | + | |
96 | +def verbose(app, message): | |
97 | + if UseLogging: | |
98 | + logger.verbose(message) | |
99 | + else: | |
100 | + app.verbose(message) | |
101 | + | |
102 | + | |
103 | --- a/Documentation/sphinx/kfigure.py | |
104 | +++ b/Documentation/sphinx/kfigure.py | |
105 | @@ -60,6 +60,8 @@ import sphinx | |
106 | from sphinx.util.nodes import clean_astext | |
107 | from six import iteritems | |
108 | ||
109 | +import kernellog | |
110 | + | |
111 | PY3 = sys.version_info[0] == 3 | |
112 | ||
113 | if PY3: | |
114 | @@ -171,20 +173,20 @@ def setupTools(app): | |
115 | This function is called once, when the builder is initiated. | |
116 | """ | |
117 | global dot_cmd, convert_cmd # pylint: disable=W0603 | |
118 | - app.verbose("kfigure: check installed tools ...") | |
119 | + kernellog.verbose(app, "kfigure: check installed tools ...") | |
120 | ||
121 | dot_cmd = which('dot') | |
122 | convert_cmd = which('convert') | |
123 | ||
124 | if dot_cmd: | |
125 | - app.verbose("use dot(1) from: " + dot_cmd) | |
126 | + kernellog.verbose(app, "use dot(1) from: " + dot_cmd) | |
127 | else: | |
128 | - app.warn("dot(1) not found, for better output quality install " | |
129 | - "graphviz from http://www.graphviz.org") | |
130 | + kernellog.warn(app, "dot(1) not found, for better output quality install " | |
131 | + "graphviz from http://www.graphviz.org") | |
132 | if convert_cmd: | |
133 | - app.verbose("use convert(1) from: " + convert_cmd) | |
134 | + kernellog.verbose(app, "use convert(1) from: " + convert_cmd) | |
135 | else: | |
136 | - app.warn( | |
137 | + kernellog.warn(app, | |
138 | "convert(1) not found, for SVG to PDF conversion install " | |
139 | "ImageMagick (https://www.imagemagick.org)") | |
140 | ||
141 | @@ -220,12 +222,13 @@ def convert_image(img_node, translator, | |
142 | ||
143 | # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages | |
144 | ||
145 | - app.verbose('assert best format for: ' + img_node['uri']) | |
146 | + kernellog.verbose(app, 'assert best format for: ' + img_node['uri']) | |
147 | ||
148 | if in_ext == '.dot': | |
149 | ||
150 | if not dot_cmd: | |
151 | - app.verbose("dot from graphviz not available / include DOT raw.") | |
152 | + kernellog.verbose(app, | |
153 | + "dot from graphviz not available / include DOT raw.") | |
154 | img_node.replace_self(file2literal(src_fname)) | |
155 | ||
156 | elif translator.builder.format == 'latex': | |
157 | @@ -252,7 +255,8 @@ def convert_image(img_node, translator, | |
158 | ||
159 | if translator.builder.format == 'latex': | |
160 | if convert_cmd is None: | |
161 | - app.verbose("no SVG to PDF conversion available / include SVG raw.") | |
162 | + kernellog.verbose(app, | |
163 | + "no SVG to PDF conversion available / include SVG raw.") | |
164 | img_node.replace_self(file2literal(src_fname)) | |
165 | else: | |
166 | dst_fname = path.join(translator.builder.outdir, fname + '.pdf') | |
167 | @@ -265,18 +269,19 @@ def convert_image(img_node, translator, | |
168 | _name = dst_fname[len(translator.builder.outdir) + 1:] | |
169 | ||
170 | if isNewer(dst_fname, src_fname): | |
171 | - app.verbose("convert: {out}/%s already exists and is newer" % _name) | |
172 | + kernellog.verbose(app, | |
173 | + "convert: {out}/%s already exists and is newer" % _name) | |
174 | ||
175 | else: | |
176 | ok = False | |
177 | mkdir(path.dirname(dst_fname)) | |
178 | ||
179 | if in_ext == '.dot': | |
180 | - app.verbose('convert DOT to: {out}/' + _name) | |
181 | + kernellog.verbose(app, 'convert DOT to: {out}/' + _name) | |
182 | ok = dot2format(app, src_fname, dst_fname) | |
183 | ||
184 | elif in_ext == '.svg': | |
185 | - app.verbose('convert SVG to: {out}/' + _name) | |
186 | + kernellog.verbose(app, 'convert SVG to: {out}/' + _name) | |
187 | ok = svg2pdf(app, src_fname, dst_fname) | |
188 | ||
189 | if not ok: | |
190 | @@ -305,7 +310,8 @@ def dot2format(app, dot_fname, out_fname | |
191 | with open(out_fname, "w") as out: | |
192 | exit_code = subprocess.call(cmd, stdout = out) | |
193 | if exit_code != 0: | |
194 | - app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd))) | |
195 | + kernellog.warn(app, | |
196 | + "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) | |
197 | return bool(exit_code == 0) | |
198 | ||
199 | def svg2pdf(app, svg_fname, pdf_fname): | |
200 | @@ -322,7 +328,7 @@ def svg2pdf(app, svg_fname, pdf_fname): | |
201 | # use stdout and stderr from parent | |
202 | exit_code = subprocess.call(cmd) | |
203 | if exit_code != 0: | |
204 | - app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd))) | |
205 | + kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) | |
206 | return bool(exit_code == 0) | |
207 | ||
208 | ||
209 | @@ -415,15 +421,15 @@ def visit_kernel_render(self, node): | |
210 | app = self.builder.app | |
211 | srclang = node.get('srclang') | |
212 | ||
213 | - app.verbose('visit kernel-render node lang: "%s"' % (srclang)) | |
214 | + kernellog.verbose(app, 'visit kernel-render node lang: "%s"' % (srclang)) | |
215 | ||
216 | tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) | |
217 | if tmp_ext is None: | |
218 | - app.warn('kernel-render: "%s" unknown / include raw.' % (srclang)) | |
219 | + kernellog.warn(app, 'kernel-render: "%s" unknown / include raw.' % (srclang)) | |
220 | return | |
221 | ||
222 | if not dot_cmd and tmp_ext == '.dot': | |
223 | - app.verbose("dot from graphviz not available / include raw.") | |
224 | + kernellog.verbose(app, "dot from graphviz not available / include raw.") | |
225 | return | |
226 | ||
227 | literal_block = node[0] |