From 290d5388993eb40b9d5632aefb864cf1012a2bcc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Feb 2020 10:00:01 +0100 Subject: scripts: documentation-file-ref-check: improve :doc: handling There are some issues at the script with regards to :doc: tags: - It doesn't escape files under Documentation/sphinx, leading to false positives; - It doesn't handle root URLs, like :doc:`/x86/boot`; - It doesn't output the file with a bad reference. Address those things, in order to remove false positives from the list of problems. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 7784c54aa38b..997202a18ddb 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -51,7 +51,9 @@ open IN, "git grep ':doc:\`' Documentation/|" or die "Failed to run git grep"; while () { next if (!m,^([^:]+):.*\:doc\:\`([^\`]+)\`,); + next if (m,sphinx/,); + my $file = $1; my $d = $1; my $doc_ref = $2; @@ -60,7 +62,12 @@ while () { $d =~ s,(.*/).*,$1,; $f =~ s,.*\<([^\>]+)\>,$1,; - $f ="$d$f.rst"; + if ($f =~ m,^/,) { + $f = "$f.rst"; + $f =~ s,^/,Documentation/,; + } else { + $f = "$d$f.rst"; + } next if (grep -e, glob("$f")); @@ -69,7 +76,7 @@ while () { } $doc_fix++; - print STDERR "$f: :doc:`$doc_ref`\n"; + print STDERR "$file: :doc:`$doc_ref`\n"; } close IN; -- cgit v1.2.3 From 021622df556b7213cffec1c0713f093fc7d045e3 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Wed, 19 Feb 2020 16:34:42 +0100 Subject: docs: add a script to check sysctl docs This script allows sysctl documentation to be checked against the kernel source code, to identify missing or obsolete entries. Running it against 5.5 shows for example that sysctl/kernel.rst has two obsolete entries and is missing 52 entries. Signed-off-by: Stephen Kitt Signed-off-by: Jonathan Corbet --- scripts/check-sysctl-docs | 181 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100755 scripts/check-sysctl-docs (limited to 'scripts') diff --git a/scripts/check-sysctl-docs b/scripts/check-sysctl-docs new file mode 100755 index 000000000000..8bcb9e26c7bc --- /dev/null +++ b/scripts/check-sysctl-docs @@ -0,0 +1,181 @@ +#!/usr/bin/gawk -f +# SPDX-License-Identifier: GPL-2.0 + +# Script to check sysctl documentation against source files +# +# Copyright (c) 2020 Stephen Kitt + +# Example invocation: +# scripts/check-sysctl-docs -vtable="kernel" \ +# Documentation/admin-guide/sysctl/kernel.rst \ +# $(git grep -l register_sysctl_) +# +# Specify -vdebug=1 to see debugging information + +BEGIN { + if (!table) { + print "Please specify the table to look for using the table variable" > "/dev/stderr" + exit 1 + } +} + +# The following globals are used: +# children: maps ctl_table names and procnames to child ctl_table names +# documented: maps documented entries (each key is an entry) +# entries: maps ctl_table names and procnames to counts (so +# enumerating the subkeys for a given ctl_table lists its +# procnames) +# files: maps procnames to source file names +# paths: maps ctl_path names to paths +# curpath: the name of the current ctl_path struct +# curtable: the name of the current ctl_table struct +# curentry: the name of the current proc entry (procname when parsing +# a ctl_table, constructed path when parsing a ctl_path) + + +# Remove punctuation from the given value +function trimpunct(value) { + while (value ~ /^["&]/) { + value = substr(value, 2) + } + while (value ~ /[]["&,}]$/) { + value = substr(value, 1, length(value) - 1) + } + return value +} + +# Print the information for the given entry +function printentry(entry) { + seen[entry]++ + printf "* %s from %s", entry, file[entry] + if (documented[entry]) { + printf " (documented)" + } + print "" +} + + +# Stage 1: build the list of documented entries +FNR == NR && /^=+$/ { + if (prevline ~ /Documentation for/) { + # This is the main title + next + } + + # The previous line is a section title, parse it + $0 = prevline + if (debug) print "Parsing " $0 + inbrackets = 0 + for (i = 1; i <= NF; i++) { + if (length($i) == 0) { + continue + } + if (!inbrackets && substr($i, 1, 1) == "(") { + inbrackets = 1 + } + if (!inbrackets) { + token = trimpunct($i) + if (length(token) > 0 && token != "and") { + if (debug) print trimpunct($i) + documented[trimpunct($i)]++ + } + } + if (inbrackets && substr($i, length($i), 1) == ")") { + inbrackets = 0 + } + } +} + +FNR == NR { + prevline = $0 + next +} + + +# Stage 2: process each file and find all sysctl tables +BEGINFILE { + delete children + delete entries + delete paths + curpath = "" + curtable = "" + curentry = "" + if (debug) print "Processing file " FILENAME +} + +/^static struct ctl_path/ { + match($0, /static struct ctl_path ([^][]+)/, tables) + curpath = tables[1] + if (debug) print "Processing path " curpath +} + +/^static struct ctl_table/ { + match($0, /static struct ctl_table ([^][]+)/, tables) + curtable = tables[1] + if (debug) print "Processing table " curtable +} + +/^};$/ { + curpath = "" + curtable = "" + curentry = "" +} + +curpath && /\.procname[\t ]*=[\t ]*".+"/ { + match($0, /.procname[\t ]*=[\t ]*"([^"]+)"/, names) + if (curentry) { + curentry = curentry "/" names[1] + } else { + curentry = names[1] + } + if (debug) print "Setting path " curpath " to " curentry + paths[curpath] = curentry +} + +curtable && /\.procname[\t ]*=[\t ]*".+"/ { + match($0, /.procname[\t ]*=[\t ]*"([^"]+)"/, names) + curentry = names[1] + if (debug) print "Adding entry " curentry " to table " curtable + entries[curtable][curentry]++ + file[curentry] = FILENAME +} + +/\.child[\t ]*=/ { + child = trimpunct($NF) + if (debug) print "Linking child " child " to table " curtable " entry " curentry + children[curtable][curentry] = child +} + +/register_sysctl_table\(.*\)/ { + match($0, /register_sysctl_table\(([^)]+)\)/, tables) + if (debug) print "Registering table " tables[1] + if (children[tables[1]][table]) { + for (entry in entries[children[tables[1]][table]]) { + printentry(entry) + } + } +} + +/register_sysctl_paths\(.*\)/ { + match($0, /register_sysctl_paths\(([^)]+), ([^)]+)\)/, tables) + if (debug) print "Attaching table " tables[2] " to path " tables[1] + if (paths[tables[1]] == table) { + for (entry in entries[tables[2]]) { + printentry(entry) + } + } + split(paths[tables[1]], components, "/") + if (length(components) > 1 && components[1] == table) { + # Count the first subdirectory as seen + seen[components[2]]++ + } +} + + +END { + for (entry in documented) { + if (!seen[entry]) { + print "No implementation for " entry + } + } +} -- cgit v1.2.3 From c428cd52282dcc967b2a936d80f1eec4cb80d6d5 Mon Sep 17 00:00:00 2001 From: Tim Bird Date: Mon, 24 Feb 2020 18:34:41 -0700 Subject: scripts/sphinx-pre-install: add '-p python3' to virtualenv With Ubuntu 16.04 (and presumably Debian distros of the same age), the instructions for setting up a python virtual environment should do so with the python 3 interpreter. On these older distros, the default python (and virtualenv command) might be python2 based. Some of the packages that sphinx relies on are now only available for python3. If you don't specify the python3 interpreter for the virtualenv, you get errors when doing the pip installs for various packages Fix this by adding '-p python3' to the virtualenv recommendation line. Signed-off-by: Tim Bird Link: https://lore.kernel.org/r/1582594481-23221-1-git-send-email-tim.bird@sony.com Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index a8f0c002a340..fa3fb05cd54b 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -701,11 +701,26 @@ sub check_needs() } else { my $rec_activate = "$virtenv_dir/bin/activate"; my $virtualenv = findprog("virtualenv-3"); + my $rec_python3 = ""; $virtualenv = findprog("virtualenv-3.5") if (!$virtualenv); $virtualenv = findprog("virtualenv") if (!$virtualenv); $virtualenv = "virtualenv" if (!$virtualenv); - printf "\t$virtualenv $virtenv_dir\n"; + my $rel = ""; + if (index($system_release, "Ubuntu") != -1) { + $rel = $1 if ($system_release =~ /Ubuntu\s+(\d+)[.]/); + if ($rel && $rel >= 16) { + $rec_python3 = " -p python3"; + } + } + if (index($system_release, "Debian") != -1) { + $rel = $1 if ($system_release =~ /Debian\s+(\d+)/); + if ($rel && $rel >= 7) { + $rec_python3 = " -p python3"; + } + } + + printf "\t$virtualenv$rec_python3 $virtenv_dir\n"; printf "\t. $rec_activate\n"; printf "\tpip install -r $requirement_file\n"; deactivate_help(); -- cgit v1.2.3 From 2b4cbd5c950525b6d4d2cd384dcefdd95fedabe3 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 2 Mar 2020 15:24:04 -0700 Subject: docs: move gcc-plugins to the kbuild manual Information about GCC plugins is relevant to kernel building, so move this document to the kbuild manual. Acked-by: Masahiro Yamada Signed-off-by: Jonathan Corbet --- scripts/gcc-plugins/Kconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig index e3569543bdac..f8ca236d6165 100644 --- a/scripts/gcc-plugins/Kconfig +++ b/scripts/gcc-plugins/Kconfig @@ -23,7 +23,7 @@ menuconfig GCC_PLUGINS GCC plugins are loadable modules that provide extra features to the compiler. They are useful for runtime instrumentation and static analysis. - See Documentation/core-api/gcc-plugins.rst for details. + See Documentation/kbuild/gcc-plugins.rst for details. if GCC_PLUGINS -- cgit v1.2.3