From patchwork Wed May 22 20:50:27 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164900 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328588ili; Wed, 22 May 2019 13:51:28 -0700 (PDT) X-Google-Smtp-Source: APXvYqyUaXH0PDDsj6wfQ2yx3MOF924Us/K5oC4fzMdwpoJpR6LIXnJRAcHswuqaVcFB5Fu76O7e X-Received: by 2002:aa7:9e51:: with SMTP id z17mr98041885pfq.212.1558558288307; Wed, 22 May 2019 13:51:28 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558288; cv=none; d=google.com; s=arc-20160816; b=Jt79rNcA0q1jrSFDjR2TTlSwFpmypcjWUOSfbKIyHoaIviFGW4UAjdOnaM1DjX/nQv oa6gxiDLP92fuEKyIKY9GV+3IlprSvrfAxVjI4QPPS7k9M6UTJaQr/C7YRoKYlWgtFzT KeH6JPmtiSwk/fYvSxS4yVnvy3ADyQwX4pmWex2RD/RqJ9Mhjx9gfKr0eQFNGXSjKoXy heqL2pguMyFITcWdCwKi/yFK+9PPlCkf8ptEnxxUHhWhxFc6YNKhKMECJRqumHTmY4cK FOPEv+fylsRXvMgodgS8elBybnDJGGtw0+Pw+dKHruQuBLuxUqSIpyn3UayB+3AUhgqo 05DQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=F3XvMF9VGF8CxCJtLpFluyhw+xu5U10EfawPI/QrLco=; b=gZ0jMpZ2x0Rayf0pLelcxOFU9fX5+ewqgspuBzU1Vs8D2Un4ZIVSMVZUebyolvTAbI 3LI+Gwj3dpcpRz5tpxQU3cCdQ5q0jM6EqzgrZ5s23BL1714uASYbmP977UVq3z7iAg9q ihqwbUvTL5VizgKxmZrC2xMzx8OW42NbeLKwFxJSyeWxtLwd3dtcCB3V0vxxV5Jh6dWx +cmHOrZe5MtwFZNNSfg+2K3ARzcm4hJYx+4XGicQvPe/pAlZXMdk6+qGKlnF2YqeVNFL B1Z97GBf0z6QzjqHvoai6vsmboL0ktPNiUWfn52MugjsYw2QAJnYeoiBrHMMbkYgElBo /Cuw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id q89si2818623pfa.155.2019.05.22.13.51.27; Wed, 22 May 2019 13:51:28 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730521AbfEVUv0 (ORCPT + 30 others); Wed, 22 May 2019 16:51:26 -0400 Received: from ms.lwn.net ([45.79.88.28]:49324 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730150AbfEVUu5 (ORCPT ); Wed, 22 May 2019 16:50:57 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 6B6456EC; Wed, 22 May 2019 20:50:56 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet Subject: [PATCH 1/8] doc: Cope with Sphinx logging deprecations Date: Wed, 22 May 2019 14:50:27 -0600 Message-Id: <20190522205034.25724-2-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Recent versions of sphinx will emit messages like: /stuff/k/git/kernel/Documentation/sphinx/kerneldoc.py:103: RemovedInSphinx20Warning: app.warning() is now deprecated. Use sphinx.util.logging instead. Switch to sphinx.util.logging to make this unsightly message go away. Alas, that interface was only added in version 1.6, so we have to add a version check to keep things working with older sphinxes. Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kerneldoc.py | 12 ++++++---- Documentation/sphinx/kernellog.py | 28 ++++++++++++++++++++++ Documentation/sphinx/kfigure.py | 40 ++++++++++++++++++------------- 3 files changed, 59 insertions(+), 21 deletions(-) create mode 100644 Documentation/sphinx/kernellog.py -- 2.21.0 diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 9d0a7f08f93b..200c8aa4a04f 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -39,6 +39,8 @@ from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive from sphinx.ext.autodoc import AutodocReporter +import kernellog + __version__ = '1.0' class KernelDocDirective(Directive): @@ -90,7 +92,8 @@ class KernelDocDirective(Directive): cmd += [filename] try: - env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) + kernellog.verbose(env.app, + 'calling kernel-doc \'%s\'' % (" ".join(cmd))) p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) out, err = p.communicate() @@ -100,7 +103,8 @@ class KernelDocDirective(Directive): if p.returncode != 0: sys.stderr.write(err) - env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + kernellog.warn(env.app, + 'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] elif env.config.kerneldoc_verbosity > 0: sys.stderr.write(err) @@ -132,8 +136,8 @@ class KernelDocDirective(Directive): return node.children except Exception as e: # pylint: disable=W0703 - env.app.warn('kernel-doc \'%s\' processing failed with: %s' % - (" ".join(cmd), str(e))) + kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] def setup(app): diff --git a/Documentation/sphinx/kernellog.py b/Documentation/sphinx/kernellog.py new file mode 100644 index 000000000000..af924f51a7dc --- /dev/null +++ b/Documentation/sphinx/kernellog.py @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Sphinx has deprecated its older logging interface, but the replacement +# only goes back to 1.6. So here's a wrapper layer to keep around for +# as long as we support 1.4. +# +import sphinx + +if sphinx.__version__[:3] >= '1.6': + UseLogging = True + from sphinx.util import logging + logger = logging.getLogger('kerneldoc') +else: + UseLogging = False + +def warn(app, message): + if UseLogging: + logger.warning(message) + else: + app.warn(message) + +def verbose(app, message): + if UseLogging: + logger.verbose(message) + else: + app.verbose(message) + + diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index b97228d2cc0e..fbfe6693bb60 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -60,6 +60,8 @@ import sphinx from sphinx.util.nodes import clean_astext from six import iteritems +import kernellog + PY3 = sys.version_info[0] == 3 if PY3: @@ -171,20 +173,20 @@ def setupTools(app): This function is called once, when the builder is initiated. """ global dot_cmd, convert_cmd # pylint: disable=W0603 - app.verbose("kfigure: check installed tools ...") + kernellog.verbose(app, "kfigure: check installed tools ...") dot_cmd = which('dot') convert_cmd = which('convert') if dot_cmd: - app.verbose("use dot(1) from: " + dot_cmd) + kernellog.verbose(app, "use dot(1) from: " + dot_cmd) else: - app.warn("dot(1) not found, for better output quality install " - "graphviz from http://www.graphviz.org") + kernellog.warn(app, "dot(1) not found, for better output quality install " + "graphviz from http://www.graphviz.org") if convert_cmd: - app.verbose("use convert(1) from: " + convert_cmd) + kernellog.verbose(app, "use convert(1) from: " + convert_cmd) else: - app.warn( + kernellog.warn(app, "convert(1) not found, for SVG to PDF conversion install " "ImageMagick (https://www.imagemagick.org)") @@ -220,12 +222,13 @@ def convert_image(img_node, translator, src_fname=None): # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages - app.verbose('assert best format for: ' + img_node['uri']) + kernellog.verbose(app, 'assert best format for: ' + img_node['uri']) if in_ext == '.dot': if not dot_cmd: - app.verbose("dot from graphviz not available / include DOT raw.") + kernellog.verbose(app, + "dot from graphviz not available / include DOT raw.") img_node.replace_self(file2literal(src_fname)) elif translator.builder.format == 'latex': @@ -252,7 +255,8 @@ def convert_image(img_node, translator, src_fname=None): if translator.builder.format == 'latex': if convert_cmd is None: - app.verbose("no SVG to PDF conversion available / include SVG raw.") + kernellog.verbose(app, + "no SVG to PDF conversion available / include SVG raw.") img_node.replace_self(file2literal(src_fname)) else: dst_fname = path.join(translator.builder.outdir, fname + '.pdf') @@ -265,18 +269,19 @@ def convert_image(img_node, translator, src_fname=None): _name = dst_fname[len(translator.builder.outdir) + 1:] if isNewer(dst_fname, src_fname): - app.verbose("convert: {out}/%s already exists and is newer" % _name) + kernellog.verbose(app, + "convert: {out}/%s already exists and is newer" % _name) else: ok = False mkdir(path.dirname(dst_fname)) if in_ext == '.dot': - app.verbose('convert DOT to: {out}/' + _name) + kernellog.verbose(app, 'convert DOT to: {out}/' + _name) ok = dot2format(app, src_fname, dst_fname) elif in_ext == '.svg': - app.verbose('convert SVG to: {out}/' + _name) + kernellog.verbose(app, 'convert SVG to: {out}/' + _name) ok = svg2pdf(app, src_fname, dst_fname) if not ok: @@ -305,7 +310,8 @@ def dot2format(app, dot_fname, out_fname): with open(out_fname, "w") as out: exit_code = subprocess.call(cmd, stdout = out) if exit_code != 0: - app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + kernellog.warn(app, + "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) return bool(exit_code == 0) def svg2pdf(app, svg_fname, pdf_fname): @@ -322,7 +328,7 @@ def svg2pdf(app, svg_fname, pdf_fname): # use stdout and stderr from parent exit_code = subprocess.call(cmd) if exit_code != 0: - app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd))) return bool(exit_code == 0) @@ -415,15 +421,15 @@ def visit_kernel_render(self, node): app = self.builder.app srclang = node.get('srclang') - app.verbose('visit kernel-render node lang: "%s"' % (srclang)) + kernellog.verbose(app, 'visit kernel-render node lang: "%s"' % (srclang)) tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) if tmp_ext is None: - app.warn('kernel-render: "%s" unknown / include raw.' % (srclang)) + kernellog.warn(app, 'kernel-render: "%s" unknown / include raw.' % (srclang)) return if not dot_cmd and tmp_ext == '.dot': - app.verbose("dot from graphviz not available / include raw.") + kernellog.verbose(app, "dot from graphviz not available / include raw.") return literal_block = node[0] From patchwork Wed May 22 20:50:28 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164893 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328235ili; Wed, 22 May 2019 13:51:00 -0700 (PDT) X-Google-Smtp-Source: APXvYqw5p1oYzPsBhPYDqwl3eh/p4Wmsfts7iOaUnii/pQ+NFBWgb+rOxeABEl2A2tpueWBJs76I X-Received: by 2002:a63:8f09:: with SMTP id n9mr63447677pgd.249.1558558259984; Wed, 22 May 2019 13:50:59 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558259; cv=none; d=google.com; s=arc-20160816; b=UXafMH058I94P4oF/TioUKg05H3ewo0W1pPk0EVySwV8yOdnGUj3sLVtPMH5wB+gNB 2YqVO0uJCs1fawLp7nSRq2zwZXR4wejOl//oQZymGHxBKP8sdCg/ZAvJymz6fCRN9rHg eWDM0k6cEjTmsoWOe+5nXcCuR1qRwhc5q2aq9m3euT3qTJXMHM72N4mOwBMNXOHkDojU Rh7ktv8izG9RSxT0fAptum7GzkAn91htUlfbzYQuU0q6elfQo9XNNm4tUqF+vshWr5qK ELGZGC1f6RdSk+E0464qJjzqohz+SOU9ff7tOha3xybJde1VCuA3qyepGAirE74fiJO4 Mh4A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=uqqMUX5vuJfdZZTiTtv77y0WoEFceULqccYbTnA65/Y=; b=uhwj1CAA0+zjjltcKxfpR+DCsxZs6krAelozug7cLWkaZN2p/Kw3rw3R0uKJYzSRwI xFDJn5gx/mT5bQreVNTzTP5gzheI7J6fC7GoLyqT51hLXjw6mxwtCEySJui2s5NuN5K+ d7eHHnie+RqBGSogMpRiqg03YsG/jrqdD0id9Big4XvBZWumSw3cLzKElgZTY9SDmQuO Jte4i6TswfB5iLlzF0ShoupQuutyQZlKkame14tFCNqn5RcTWmUcr2pO/4euJCUSa87X 5NC8Nm1LIAafe0iX4L9y99/tJa3BfCXYbmOmfbWTtZVuj7PBmrGjS2pLnCXGJRCvpI0j C+Yg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id cp7si27333432plb.14.2019.05.22.13.50.59; Wed, 22 May 2019 13:50:59 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730304AbfEVUu6 (ORCPT + 30 others); Wed, 22 May 2019 16:50:58 -0400 Received: from ms.lwn.net ([45.79.88.28]:49340 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729848AbfEVUu5 (ORCPT ); Wed, 22 May 2019 16:50:57 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id D9DC0128A; Wed, 22 May 2019 20:50:56 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet Subject: [PATCH 2/8] doc: Cope with the deprecation of AutoReporter Date: Wed, 22 May 2019 14:50:28 -0600 Message-Id: <20190522205034.25724-3-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org AutoReporter is going away; recent versions of sphinx emit a warning like: /stuff/k/git/kernel/Documentation/sphinx/kerneldoc.py:125: RemovedInSphinx20Warning: AutodocReporter is now deprecated. Use sphinx.util.docutils.switch_source_input() instead. Make the switch. But switch_source_input() only showed up in 1.7, so we have to do ugly version checks to keep things working in older versions. Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kerneldoc.py | 34 +++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) -- 2.21.0 diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 200c8aa4a04f..1159405cb920 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -37,7 +37,17 @@ import glob from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive -from sphinx.ext.autodoc import AutodocReporter + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter import kernellog @@ -125,13 +135,7 @@ class KernelDocDirective(Directive): lineoffset += 1 node = nodes.section() - buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter - self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) - self.state.memo.title_styles, self.state.memo.section_level = [], 0 - try: - self.state.nested_parse(result, 0, node, match_titles=1) - finally: - self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + self.do_parse(result, node) return node.children @@ -140,6 +144,20 @@ class KernelDocDirective(Directive): (" ".join(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + def do_parse(self, result, node): + if Use_SSI: + with switch_source_input(self.state, result): + self.state.nested_parse(result, 0, node, match_titles=1) + else: + save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save + + def setup(app): app.add_config_value('kerneldoc_bin', None, 'env') app.add_config_value('kerneldoc_srctree', None, 'env') From patchwork Wed May 22 20:50:29 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164899 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328524ili; Wed, 22 May 2019 13:51:23 -0700 (PDT) X-Google-Smtp-Source: APXvYqylMqL5p8Be1sBdsmOe4xcUNBN/3bMDdLjjMs9gAWJ5i2rHfjuywmJVyI5gZh9q5wDP3wS5 X-Received: by 2002:a17:902:3343:: with SMTP id a61mr92196766plc.90.1558558283401; Wed, 22 May 2019 13:51:23 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558283; cv=none; d=google.com; s=arc-20160816; b=a8bJgK+/1JE3trQE6+op5AE/gXCtFmoZR56uNVpoR5PeCgGu9StLPDFh+yOUU6vl/i HyLdLDxlkJCbsNvsGPexzlMxbziU1axF2LYoHMpRBGqu3CqskYBS84d4o8OUydnajth5 3HMqQAWg1rY0dbr7yS4bjJhZAmosJcgL0gIhL84j/nOX2aSOuXAVcVQksdktWeIrU33w VHAffRAZctiR4KKcfnmZr5dJp4jQ48ahfqVBsT2WVhKOMAzZ9c2djHqsN/3JRJyhApbK xepbglNg7X3wljZcRBwZ2xT0hzh2WCJDK/Tgehv+MyyAoq2PMpRTiAgDNvUBmJ7sYH7m GzVA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=6L4QxulFAF1wGTlg7UugW3f0X7wQimFu4JY2QjLZMt4=; b=KZU8fZCOV5XPMTEobjsQNvG5JQsgwvYzsXu0/Bz81pH5070rEFK/hBJP10JzfqvklB gJzI0uG+12so7XeMWVK5WAdQBOBXnYa/497DDznpEkJtwKHTc9nL4sszd7gLIHBVSsD7 EmWWdIPK6+H2hktDMFcuq+69lF/Lhj0DAuRjoWEsFjHaS/DeaIGpAKB4g3qaw1Vfw1M4 FxFd1O3uwpdAkXsoasEOxK/uboct1o6b4UYDnM1miOut+ihEJS+bnHemFT4lHdTG1XGr 7P9b1WfoqTDnoPBhG+V/zc7eGVBXBTLBZLvB38GM+eRn41S7G/xcg8vV5FeDjJHulnXN zSAw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id q89si2818623pfa.155.2019.05.22.13.51.23; Wed, 22 May 2019 13:51:23 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730491AbfEVUvW (ORCPT + 30 others); Wed, 22 May 2019 16:51:22 -0400 Received: from ms.lwn.net ([45.79.88.28]:49340 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730247AbfEVUu6 (ORCPT ); Wed, 22 May 2019 16:50:58 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 54C0BAB5; Wed, 22 May 2019 20:50:57 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet , Keith Busch , Mike Rapoport Subject: [PATCH 3/8] docs: fix numaperf.rst and add it to the doc tree Date: Wed, 22 May 2019 14:50:29 -0600 Message-Id: <20190522205034.25724-4-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Commit 13bac55ef7ae ("doc/mm: New documentation for memory performance") added numaperf.rst, but did not add it to the TOC tree. There was also an incorrectly marked literal block leading to this warning sequence: numaperf.rst:24: WARNING: Unexpected indentation. numaperf.rst:24: WARNING: Inline substitution_reference start-string without end-string. numaperf.rst:25: WARNING: Block quote ends without a blank line; unexpected unindent. Fix the block and add the file to the document tree. Fixes: 13bac55ef7ae ("doc/mm: New documentation for memory performance") Cc: Keith Busch Cc: Mike Rapoport Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/mm/index.rst | 1 + Documentation/admin-guide/mm/numaperf.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) -- 2.21.0 Reviewed-by: Mike Rapoport diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index 8edb35f11317..ddf8d8d33377 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -31,6 +31,7 @@ the Linux memory management. ksm memory-hotplug numa_memory_policy + numaperf pagemap soft-dirty transhuge diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index b79f70c04397..c067ed145158 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -15,7 +15,7 @@ characteristics. Some memory may share the same node as a CPU, and others are provided as memory only nodes. While memory only nodes do not provide CPUs, they may still be local to one or more compute nodes relative to other nodes. The following diagram shows one such example of two compute -nodes with local memory and a memory only node for each of compute node: +nodes with local memory and a memory only node for each of compute node:: +------------------+ +------------------+ | Compute Node 0 +-----+ Compute Node 1 | From patchwork Wed May 22 20:50:30 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164894 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328290ili; Wed, 22 May 2019 13:51:05 -0700 (PDT) X-Google-Smtp-Source: APXvYqxp9qYZiTRK9saHdg1SYWpvaasNj+00DqTjTzeb3cM4vNKFLp/Be4iBMpsb5fWSFSMRiXwv X-Received: by 2002:a17:902:8ec4:: with SMTP id x4mr10200537plo.249.1558558265226; Wed, 22 May 2019 13:51:05 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558265; cv=none; d=google.com; s=arc-20160816; b=GAdP3yaFCKS1RBXVLePiOU8JIMw8SOzj2F/wO5qKHu2DVQdHuYxd3ZyzpQ7SzGCMCY Xo0Yowd+HaxYrcxHJA+1IzBGv9Ts1pUCdHg2wp+axs0VYHJoE/H8kfhzR4aYE9prkhkN /+72bzQKL9CvE+I5ocJJxB2bYFri52lmbiZsJrtygYMw1IZiy+GPeGSCEUVzyvBxffBb +zseFKGSbZxDX3I+rmgAEin/iqY1COv9qWEixsWgLnKynntNngnKb0mnuz9RC1XSWMJ/ LkQftwif09MP2NqjHjCWmonjhSrGKDsHUvTsjcjxmDMRbb490UsPrgxJpECp9S1tJm9m Pfzg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=IJvioq1BFZcYj8e84m3Ottwv2C5Xrbu5UWSb1TznFaA=; b=h3Qi9b2DeMq+gWCSNECFgf4NLx1EsR9aC/QTm8WIsJlVcDvsgALBLwAsE0mU71HPEq DbyPXeUUP02ICUAJ5vtn4cVoCGDcD74B71JT693AIsv4IN39IxaT/XmOCE7mmWPAh3Sj TE+VychmZ2XIp6ITDr8BvS2w0Qum/Cx0y6sbCrYre/4No5QOc7iEaUoCgHccj5IksbuG /yS6j8LqYqg+1CRFPzVVi8KzxMp0tRPUU0+esTozfgy7Xd9C+jBJQSbNfU/1Wm5yBLe3 ZrUCmDPnkj+z0eGEfNfPTn3mNTkUGH3TSvwVGSC9MgKGJwqV5FHGjDrcjlp/CN8uaAbe J85Q== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id cp7si27333432plb.14.2019.05.22.13.51.04; Wed, 22 May 2019 13:51:05 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730393AbfEVUvE (ORCPT + 30 others); Wed, 22 May 2019 16:51:04 -0400 Received: from ms.lwn.net ([45.79.88.28]:49324 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730292AbfEVUu6 (ORCPT ); Wed, 22 May 2019 16:50:58 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id CD9A812B3; Wed, 22 May 2019 20:50:57 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet , George Spelvin Subject: [PATCH 4/8] lib/list_sort: fix kerneldoc build error Date: Wed, 22 May 2019 14:50:30 -0600 Message-Id: <20190522205034.25724-5-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Commit 043b3f7b6388 ("lib/list_sort: simplify and remove MAX_LIST_LENGTH_BITS") added some useful kerneldoc info, but also broke the docs build: ./lib/list_sort.c:128: WARNING: Definition list ends without a blank line; unexpected unindent. ./lib/list_sort.c:161: WARNING: Unexpected indentation. ./lib/list_sort.c:162: WARNING: Block quote ends without a blank line; unexpected unindent. Fix the offending literal block and make the error go away. Fixes: 043b3f7b6388 ("lib/list_sort: simplify and remove MAX_LIST_LENGTH_BITS") Cc: George Spelvin Signed-off-by: Jonathan Corbet --- lib/list_sort.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) -- 2.21.0 diff --git a/lib/list_sort.c b/lib/list_sort.c index 06e900c5587b..712ed1f4eb64 100644 --- a/lib/list_sort.c +++ b/lib/list_sort.c @@ -120,7 +120,8 @@ static void merge_final(void *priv, cmp_func cmp, struct list_head *head, * The latter offers a chance to save a few cycles in the comparison * (which is used by e.g. plug_ctx_cmp() in block/blk-mq.c). * - * A good way to write a multi-word comparison is + * A good way to write a multi-word comparison is:: + * * if (a->high != b->high) * return a->high > b->high; * if (a->middle != b->middle) From patchwork Wed May 22 20:50:31 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164897 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328399ili; Wed, 22 May 2019 13:51:14 -0700 (PDT) X-Google-Smtp-Source: APXvYqzG2UZWcuNMURvmLpr2B+lOYXoGWWnGBkJp0PibWQ2rv427XiHWgE8EdrFO1ln686fxjVMV X-Received: by 2002:a63:171c:: with SMTP id x28mr92655049pgl.12.1558558274216; Wed, 22 May 2019 13:51:14 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558274; cv=none; d=google.com; s=arc-20160816; b=uAzcC0J/k+k0Bd1vDZUf4SqxrRq3F9y3KhcCEDFtEoJEzUgS1bLs0j/WInEgZh3W3X 9pWUCNpymVaELsl/Aa6R9Ew1g/R/t+x2HR33DuHoV2LC77J+PS7UojLlTwvO1+0VM+jh VSIdl0dmHCLzEe0LEGEKVF/8aWwVlgvvhxvJ6N3i9nqehK7wZFMEu8gaB37cPaEAO51m elyiyg2CaMfW6XxdCBsoItuB15HXdMsLe5O4OHxMlufwyaJXnW65Tm/yKj/5SrfoFIYH No9wTyy4rDxQdGBL0htsoXoAIY/lP5GM1wFGX0zvp52spYcpLXtspxSRZ6UAxes+WjY7 2lZQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=F/nVhqatcf0mUzv2QLZMUC7es9gNxjd72Sov7mPqS3g=; b=mdqHaqaccCma8GppsXFxSV+Ihwi7F5DXkIIoIQ7nj6XdVd9SYNi1dOJpjvDGkUnbAa chWyAeMoyNGQ6xtdMU26R5e+D56DHWDDhCL7Mds3jbSH2iPRdIbCfxf4emLNoM2tj78G 2nj0KxVn7SGDWMK4qh9bTbrAi78OKmJTxMextqJVX/PHroGY/sZPQVmRv5iDP8fALTub 4fbYf9aR4hH9HZbGAcCY9B6lwoqnojoY+Efw0N5cyqA5jr9nc7azlwtgkuEJWhzNSjAX lRrxh5QwZo/zolsJKNWa5uRZ9Q697y628GMD/IcTDyk2y0rl3yOOjLsOIM/+YFT9SHDp eZVw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f13si28220476pga.385.2019.05.22.13.51.13; Wed, 22 May 2019 13:51:14 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730362AbfEVUvB (ORCPT + 30 others); Wed, 22 May 2019 16:51:01 -0400 Received: from ms.lwn.net ([45.79.88.28]:49340 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730305AbfEVUu6 (ORCPT ); Wed, 22 May 2019 16:50:58 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 47B461321; Wed, 22 May 2019 20:50:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet , Changbin Du Subject: [PATCH 5/8] docs: fix multiple doc build warnings in enumeration.rst Date: Wed, 22 May 2019 14:50:31 -0600 Message-Id: <20190522205034.25724-6-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The conversion of acpi/enumeration.txt to RST included one markup error, leading to many warnings like: .../firmware-guide/acpi/enumeration.rst:430: WARNING: Unexpected indentation. Add the missing colon and create some peace. Fixes: c24bc66e8157 ("Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST") Cc: Changbin Du Signed-off-by: Jonathan Corbet --- Documentation/firmware-guide/acpi/enumeration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.21.0 diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 6b32b7be8c85..850be9696931 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -423,7 +423,7 @@ will be enumerated to depends on the device ID returned by _HID. For example, the following ACPI sample might be used to enumerate an lm75-type I2C temperature sensor and match it to the driver using the Device Tree -namespace link: +namespace link:: Device (TMP0) { From patchwork Wed May 22 20:50:32 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164895 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328314ili; Wed, 22 May 2019 13:51:07 -0700 (PDT) X-Google-Smtp-Source: APXvYqx9MZJ7E8/jTYIPS1EKDMyCvM5dcFpEOcQBi9ZrOh0PC4vDkXahpC4s6DUNMLINwdVOqpZ5 X-Received: by 2002:a62:4c5:: with SMTP id 188mr38029497pfe.19.1558558266897; Wed, 22 May 2019 13:51:06 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558266; cv=none; d=google.com; s=arc-20160816; b=GB9jU67QA8GrIfl7FyYGx3BGfP+aZicM1kJ3T06C62C/dlIxKayZqGJfkAJR9MDxl/ jnUv06vD7AP+Z0waIrvEwu6nflKOxBLlClYkROfhCBc+s5ObDx/ukD/GrKDO+n7kXfY9 JuvPrT3nx7YPuumWhWnosTFIX7b0BrxKbV2pELj4IZpwkbBPKFolMHOcGiahyMjql8Uo oPzeMsbu1swPdYRaepDaXQuxv5tyqEoDrSpJCLyfjUqNLjFGxchsuQfK/EPNHufA/ACG yR1y7vBevkbRBE6uWH54XIgjUcbRfRUTIPzEUgcleB3kGwiDpi5TQHof1CHjo7T2NVzc l8cw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=jpyN7dVewYpBXvqI5N7QECzLF36iAiTWk/owPq0e/3U=; b=FqcyeHa8Lzln157D9Ol8a/Hh9LZcWwDMGsmu7tYUo6b45KgAfmlZF4bxr9znkQ01uE NdV47ykH/Bot98UfVzJsUw03foRvgo6PmKMTI9oCSi49YPB8fQZhVYKqe61x0SihPuDq CL/YVwyxjKjDW0Ni5naDcQ+MZCgaUpcat1I0bZRGPKGEIE1rVW/oQ3Wj7XMG4oXRJsbY pXRTOd3WGnQ1pgVNHlBS6i5CEsKE8vYh7cWa1Rn8IokrGCOCnJRMIWVOYugYqWvopZj/ QH/thEVhC5F6MIdHrOI76xjC7T9n7EPN+bokYusZ8hw2PvgclyugvhA5XFC7u4ZTJUt0 8lAw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id cp7si27333432plb.14.2019.05.22.13.51.06; Wed, 22 May 2019 13:51:06 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730416AbfEVUvG (ORCPT + 30 others); Wed, 22 May 2019 16:51:06 -0400 Received: from ms.lwn.net ([45.79.88.28]:49324 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729848AbfEVUu7 (ORCPT ); Wed, 22 May 2019 16:50:59 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id B83CA130D; Wed, 22 May 2019 20:50:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet Subject: [PATCH 6/8] docs/gpu: fix a documentation build break in i915.rst Date: Wed, 22 May 2019 14:50:32 -0600 Message-Id: <20190522205034.25724-7-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Documentation/gpu/i915.rst is not included in the TOC tree, but newer versions of sphinx parse it anyway. That leads to this hard build failure: > Global GTT Fence Handling > ~~~~~~~~~~~~~~~~~~~~~~~~~ > > reST markup error: > /stuff/k/git/kernel/Documentation/gpu/i915.rst:403: (SEVERE/4) Title level inconsistent: Make the underlining consistent and restore a working docs build. Signed-off-by: Jonathan Corbet --- Documentation/gpu/i915.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) -- 2.21.0 diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 055df45596c1..cf9ff64753cc 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -401,13 +401,13 @@ GTT Fences and Swizzling :internal: Global GTT Fence Handling -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c :doc: fence register handling Hardware Tiling and Swizzling Details -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c :doc: tiling swizzling details From patchwork Wed May 22 20:50:33 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164898 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328429ili; Wed, 22 May 2019 13:51:18 -0700 (PDT) X-Google-Smtp-Source: APXvYqxKbf3qSDiVU69HLOsS970wkzRuCFFOtHmBGFcYFTqyazSSERE97tkT5PKPqeen1V2uLIKI X-Received: by 2002:a17:902:424:: with SMTP id 33mr92951644ple.102.1558558278071; Wed, 22 May 2019 13:51:18 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558278; cv=none; d=google.com; s=arc-20160816; b=rgnSZi9x1QTQZXBM7BN2fN+UcYUNm7+MNvRBI4TIFmG5wPygoLoTMUc64FUA6jmJZM c4IIfYkH5fpAAM3S3wjlOKwQOac6Z9Ug5Gs/7qgVdlKkQcQlVPcOF8tfrE6tS3dpjyvd ak5+DqOh16znd6jck2Jq+2fCb2eUKmICQV9v6Bzdjkzfz5MywsIYCnLpVpahDLHxwyGi T5x1OGTnjpNzdNbn3TBIj/FqPkrSGVEq2GJ9AM7s30gTwi7JEQPYKSq3lVp37FNPUmrN mseNc/KCDhefIj0Zu35zhLuNWazmR5ATxqSR2nzVDt9RgWvGm7dKliVtK3mWYi2lKCPe CdGw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=40IsZ2QSF57jokoQgnLowe8JybRRidr3M86Y3Kub/n0=; b=O42zl8WFZJyI05Gi3/APCKF5AdkzQOMyw1YDfjiMFy0fQnMXY+NzjAKhsWfAIhTwLw t/pjvQsEb0PudZycqTSvCVJsyH8iiE+qJI5EvegZq0ozqTc7X+xeiKQRzFHlv6ikTp02 5wbagvv3V5aAY6jggS3f1iA1Yum9b5MED5GgcWqKTvsH1KzGbklR9yJ4jlfovUsQDgTD JeCP4Uyn2NBKiGxY8RV7VX69XeE93Zk/NE+39Qgtj4PD+jZidBnBjuOXJv1gG2aHnIYP 8BOe7JFQPNaxqtxWlyiTUZokwaW5tcdthhrdGr/Z3qU2AlMxjFNrWOV7WpH4aBZn7HFH 4+kQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f13si28220476pga.385.2019.05.22.13.51.17; Wed, 22 May 2019 13:51:18 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730458AbfEVUvQ (ORCPT + 30 others); Wed, 22 May 2019 16:51:16 -0400 Received: from ms.lwn.net ([45.79.88.28]:49388 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730327AbfEVUu7 (ORCPT ); Wed, 22 May 2019 16:50:59 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 292AD1427; Wed, 22 May 2019 20:50:59 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Jonathan Corbet Subject: [PATCH 7/8] docs: Fix conf.py for Sphinx 2.0 Date: Wed, 22 May 2019 14:50:33 -0600 Message-Id: <20190522205034.25724-8-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Our version check in Documentation/conf.py never envisioned a world where Sphinx moved beyond 1.x. Now that the unthinkable has happened, fix our version check to handle higher version numbers correctly. Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.21.0 diff --git a/Documentation/conf.py b/Documentation/conf.py index 72647a38b5c2..7ace3f8852bd 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -37,7 +37,7 @@ needs_sphinx = '1.3' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig'] # The name of the math extension changed on Sphinx 1.4 -if major == 1 and minor > 3: +if (major == 1 and minor > 3) or (major > 1): extensions.append("sphinx.ext.imgmath") else: extensions.append("sphinx.ext.pngmath") From patchwork Wed May 22 20:50:34 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 164896 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1328338ili; Wed, 22 May 2019 13:51:08 -0700 (PDT) X-Google-Smtp-Source: APXvYqyfvXw8nYnKT0QJYxaMSSw1aLt9EbMbH/rAyzWGgdO1Cpo2XgUQe6Cw4q08AXjzMEUmfbER X-Received: by 2002:a17:902:e683:: with SMTP id cn3mr69871560plb.86.1558558268848; Wed, 22 May 2019 13:51:08 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558558268; cv=none; d=google.com; s=arc-20160816; b=wFBV2KIcfjlmrkn62arnG73Q/tcP8x+evrkFKv5kN619aRPFv1dzu2FUK12fS0U1hr HX+gT8CeIvio1gHcoQXIfvLpyrudx61Ml+vkRYMTVoF6Pp2dVfya5wCNWnqJIp6CKNJr PghfVOiWCOHDMGaOr4Guy4OGDj8/zOeL+DLNPczH1l/YOfu9bgY7I3BdSi1eu+QJPSdn DbXomHZVCnZOYRG46O4DKyTa7GC8ea1oa4ukdBzb9NY2Ml7VDY8Tkd5rsLLLGxOiViYm OwO+NHpSzQojmTpFZ4ztIEE5EqEM9wn1Q3QnJxeTSipWeeJ+M7kMqzfQueooDSoexr1Y IgSg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=ARC5Fk56aYrZSDtuk2/hMcqIxkgBmE5uwnJJ48nDdcg=; b=jAIh0rd08VAkFyEXqhRMrUUfWYyf/2ltA9KyiXvzVAtLUqjfLORJscUAPpbpPI2sXN JdlwYREcEbwkB8Kc6Fc6JmdZzhck2O6LwlxccTypQKMqO+uwh9/1APK1dlnkqq/PAB4I MKy6XZrYX1iVg09BkScl41OSF5H/KdX24wb1l86plA6RgrulHzYwUz1yvMqBC64vXIhN Lh5xJ/IcXHm8nkG0F7ZiAPDSzaHteJQh2y8bGXsOO2OP9O+MXw12RkZWkvWIe4OGV3qG w2391hbgUP5nZU4HeRd/tneti/IEIzny4ER2cSPsvFWC0Rl6NrbSC2PuiLJWORYQVoGJ nErQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f13si28220476pga.385.2019.05.22.13.51.08; Wed, 22 May 2019 13:51:08 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730435AbfEVUvH (ORCPT + 30 others); Wed, 22 May 2019 16:51:07 -0400 Received: from ms.lwn.net ([45.79.88.28]:49398 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730341AbfEVUvA (ORCPT ); Wed, 22 May 2019 16:51:00 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 8DC681429; Wed, 22 May 2019 20:50:59 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Markus Heiser , Mauro Carvalho Chehab , Oleksandr Natalenko , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 8/8] scripts/sphinx-pre-install: make it handle Sphinx versions Date: Wed, 22 May 2019 14:50:34 -0600 Message-Id: <20190522205034.25724-9-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190522205034.25724-1-corbet@lwn.net> References: <20190522205034.25724-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Mauro Carvalho Chehab As we want to switch to a newer Sphinx version in the future, add some version detected logic, checking if the current version meets the requirement and suggesting upgrade it the version is supported but too old. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 81 ++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 7 deletions(-) -- 2.21.0 diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index f6a5c0bae31e..e667db230d0a 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -13,7 +13,7 @@ use strict; # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. -my $virtenv_dir = "sphinx_1.4"; +my $conf = "Documentation/conf.py"; my $requirement_file = "Documentation/sphinx/requirements.txt"; # @@ -26,7 +26,9 @@ my $need = 0; my $optional = 0; my $need_symlink = 0; my $need_sphinx = 0; +my $rec_sphinx_upgrade = 0; my $install = ""; +my $virtenv_dir = "sphinx_"; # # Command line arguments @@ -201,13 +203,15 @@ sub check_missing_tex($) } } -sub check_sphinx() +sub get_sphinx_fname() { - return if findprog("sphinx-build"); + my $fname = "sphinx-build"; + return $fname if findprog($fname); - if (findprog("sphinx-build-3")) { + $fname = "sphinx-build-3"; + if (findprog($fname)) { $need_symlink = 1; - return; + return $fname; } if ($virtualenv) { @@ -219,6 +223,68 @@ sub check_sphinx() } else { add_package("python-sphinx", 0); } + + return ""; +} + +sub check_sphinx() +{ + my $min_version; + my $rec_version; + my $cur_version; + + open IN, $conf or die "Can't open $conf"; + while () { + if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) { + $min_version=$1; + last; + } + } + close IN; + + die "Can't get needs_sphinx version from $conf" if (!$min_version); + + open IN, $requirement_file or die "Can't open $requirement_file"; + while () { + if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) { + $rec_version=$1; + last; + } + } + close IN; + + die "Can't get recommended sphinx version from $requirement_file" if (!$min_version); + + my $sphinx = get_sphinx_fname(); + return if ($sphinx eq ""); + + open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error"; + while () { + if (m/^\s*sphinx-build\s+([\d\.]+)$/) { + $cur_version=$1; + last; + } + } + close IN; + + $virtenv_dir .= $rec_version; + + die "$sphinx didn't return its version" if (!$cur_version); + + printf "Sphinx version %s (minimal: %s, recommended >= %s)\n", + $cur_version, $min_version, $rec_version; + + if ($cur_version lt $min_version) { + print "Warning: Sphinx version should be >= $min_version\n\n"; + $need_sphinx = 1; + return; + } + + if ($cur_version lt $rec_version) { + print "Warning: It is recommended at least Sphinx version $rec_version.\n"; + print " To upgrade, use:\n\n"; + $rec_sphinx_upgrade = 1; + } } # @@ -540,7 +606,7 @@ sub check_needs() printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n", which("sphinx-build-3"); } - if ($need_sphinx) { + if ($need_sphinx || $rec_sphinx_upgrade) { my $activate = "$virtenv_dir/bin/activate"; if (-e "$ENV{'PWD'}/$activate") { printf "\nNeed to activate virtualenv with:\n"; @@ -554,7 +620,8 @@ sub check_needs() printf "\t$virtualenv $virtenv_dir\n"; printf "\t. $activate\n"; printf "\tpip install -r $requirement_file\n"; - $need++; + + $need++ if (!$rec_sphinx_upgrade); } } printf "\n";