Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-10 22:21:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

The Sphinx 2.0 release contained a few incompatible API changes that broke

Browse Source 
our extensions and, thus, the documentation build in general.  Who knew
 that those deprecation warnings it was outputting actually meant we should
 change something?  This set of fixes makes the build work again with
 Sphinx 2.0 and eliminates the warnings for 1.8.  As part of that, we also
 need a few fixes to the docs for places where the new Sphinx is more
 strict.
 
 It is a bit late in the cycle for this kind of change, but it does fix
 problems that people are experiencing now.
 
 There has been some talk of raising the minimum version of Sphinx we
 support.  I don't want to do that abruptly, though, so these changes add
 some glue to continue to support versions back to 1.3.  We will be adding
 some infrastructure soon to nudge users of old versions forward, with the
 idea of maybe increasing our minimum version (and removing this glue)
 sometime in the future.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAlzsYw8PHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5YGuwH+gOk2lGPpI7tsIsctUr3TTviYbu9EywGINUA
 c2pPQBHbC13F/QKkb/WArnIhM7eRMWxNy1IlrzqTTLRcAteJihoRNldLVpImxwHJ
 DaULovUHRO9uNuVORGV4RLOBUUkrguoz4X7OZooT3tluRZcL58C3Qn8MbZYiZYf1
 ZJKHVJxfSedyHYTK1H5qB9uAAvdoNGLjvK8pzA9S7HgHM9viuOlY2GTHn4uvlmI+
 qgnbVRNeEb8IRFztvKy2RyMAisx2o5v/lfpKVM+OC9EJgkpw+mw55YUdfDeNavJg
 2d3xv8zgS1TP+qAmba2uVwiRDNChTKxz72nbaqZZGOt16StRiyY=
 =hrKI
 -----END PGP SIGNATURE-----

Merge tag 'docs-5.2-fixes2' of git://git.lwn.net/linux

Pull documentation fixes from Jonathan Corbet:
 "The Sphinx 2.0 release contained a few incompatible API changes that
  broke our extensions and, thus, the documentation build in general.
  Who knew that those deprecation warnings it was outputting actually
  meant we should change something? This set of fixes makes the build
  work again with Sphinx 2.0 and eliminates the warnings for 1.8. As
  part of that, we also need a few fixes to the docs for places where
  the new Sphinx is more strict.

  It is a bit late in the cycle for this kind of change, but it does fix
  problems that people are experiencing now.

  There has been some talk of raising the minimum version of Sphinx we
  support. I don't want to do that abruptly, though, so these changes
  add some glue to continue to support versions back to 1.3. We will be
  adding some infrastructure soon to nudge users of old versions
  forward, with the idea of maybe increasing our minimum version (and
  removing this glue) sometime in the future"

* tag 'docs-5.2-fixes2' of git://git.lwn.net/linux:
  drm/i915: Maintain consistent documentation subsection ordering
  scripts/sphinx-pre-install: make it handle Sphinx versions
  docs: Fix conf.py for Sphinx 2.0
  docs: fix multiple doc build warnings in enumeration.rst
  lib/list_sort: fix kerneldoc build error
  docs: fix numaperf.rst and add it to the doc tree
  doc: Cope with the deprecation of AutoReporter
  doc: Cope with Sphinx logging deprecations
This commit is contained in:
Linus Torvalds 2019-05-29 14:36:41 -07:00
commit bec7550cca
11 changed files with 173 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/admin-guide/mm/index.rst
View File

@ -31,6 +31,7 @@ the Linux memory management.
ksm
memory-hotplug
numa_memory_policy
numaperf
pagemap
soft-dirty
transhuge

2
Documentation/admin-guide/mm/numaperf.rst
View File

@ -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 |

2
Documentation/conf.py
View File

@ -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")

2
Documentation/firmware-guide/acpi/enumeration.rst
View File

@ -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)
{

44
Documentation/sphinx/kerneldoc.py
View File

@ -37,7 +37,19 @@ 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
__version__ = '1.0'
@ -90,7 +102,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 +113,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)
@ -121,20 +135,28 @@ class KernelDocDirective(Directive):
lineoffset += 1
node = nodes.section()
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
self.do_parse(result, node)
return node.children
except Exception as e: # pylint: disable=W0703
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 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 = buf
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save
return node.children
except Exception as e: # pylint: disable=W0703
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
(" ".join(cmd), str(e)))
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
def setup(app):
app.add_config_value('kerneldoc_bin', None, 'env')

28
Documentation/sphinx/kernellog.py Normal file
View File

@ -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)

40
Documentation/sphinx/kfigure.py
View File

@ -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]

6
drivers/gpu/drm/i915/i915_reg.h
View File

@ -35,7 +35,7 @@
* macros. Do **not** mass change existing definitions just to update the style.
*
* Layout
* ''''''
* ~~~~~~
*
* Keep helper macros near the top. For example, _PIPE() and friends.
*
@ -79,7 +79,7 @@
* style. Use lower case in hexadecimal values.
*
* Naming
* ''''''
* ~~~~~~
*
* Try to name registers according to the specs. If the register name changes in
* the specs from platform to another, stick to the original name.
@ -97,7 +97,7 @@
* suffix to the name. For example, ``_SKL`` or ``_GEN8``.
*
* Examples
* ''''''''
* ~~~~~~~~
*
* (Note that the values in the example are indented using spaces instead of
* TABs to avoid misalignment in generated documentation. Use TABs in the

2
drivers/gpu/drm/i915/intel_workarounds.c
View File

@ -37,7 +37,7 @@
* costly and simplifies things. We can revisit this in the future.
*
* Layout
* ''''''
* ~~~~~~
*
* Keep things in this file ordered by WA type, as per the above (context, GT,
* display, register whitelist, batchbuffer). Then, inside each type, keep the

3
lib/list_sort.c
View File

@ -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)

86
scripts/sphinx-pre-install
View File

@ -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,73 @@ 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 (<IN>) {
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 (<IN>) {
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);
$virtenv_dir .= $rec_version;
my $sphinx = get_sphinx_fname();
return if ($sphinx eq "");
open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error";
while (<IN>) {
if (m/^\s*sphinx-build\s+([\d\.]+)$/) {
$cur_version=$1;
last;
}
# Sphinx 1.2.x uses a different format
if (m/^\s*Sphinx.*\s+([\d\.]+)$/) {
$cur_version=$1;
last;
}
}
close IN;
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 +611,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 +625,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";