2019-06-04 12:28:05

by Mauro Carvalho Chehab

Subject: [PATCH] docs: Kbuild/Makefile: allow check for missing docs at build time

While this doesn't make sense for production Kernels, in order to
avoid regressions when documents are touched, let's add a
check target at the make file.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---

Jon,

It is very common for people to shift things around and forget to rename
the documentation files.

Just on this new Kernel cycle, every time I update from linux-next I get more
broken stuff.

IMO, the best is to run the check script with COMPILE_TEST, as this will make
build robots to warn people about such breakages, with will hopefully help
to avoid regressions due to broken documentation references.


Documentation/Kconfig | 13 +++++++++++++
Documentation/Makefile | 5 +++++
Kconfig | 2 ++
scripts/documentation-file-ref-check | 9 +++++++++
4 files changed, 29 insertions(+)
create mode 100644 Documentation/Kconfig

diff --git a/Documentation/Kconfig b/Documentation/Kconfig
new file mode 100644
index 000000000000..66046fa1c341
--- /dev/null
+++ b/Documentation/Kconfig
@@ -0,0 +1,13 @@
+config WARN_MISSING_DOCUMENTS
+
+ bool "Warn if there's a missing documentation file"
+ depends on COMPILE_TEST
+ help
+ It is not uncommon that a document gets renamed.
+ This option makes the Kernel to check for missing dependencies,
+ warning when something is missing. Works only if the Kernel
+ is built from a git tree.
+
+ If unsure, select 'N'.
+
+
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2edd03b1dad6..89857285a024 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -4,6 +4,11 @@

subdir-y := devicetree/bindings/

+# Check for broken documentation file references
+ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
+$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
+endif
+
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
diff --git a/Kconfig b/Kconfig
index 48a80beab685..990b0c390dfc 100644
--- a/Kconfig
+++ b/Kconfig
@@ -30,3 +30,5 @@ source "crypto/Kconfig"
source "lib/Kconfig"

source "lib/Kconfig.debug"
+
+source "Documentation/Kconfig"
diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check
index ff16db269079..440227bb55a9 100755
--- a/scripts/documentation-file-ref-check
+++ b/scripts/documentation-file-ref-check
@@ -22,9 +22,16 @@ $scriptname =~ s,.*/([^/]+/),$1,;
# Parse arguments
my $help = 0;
my $fix = 0;
+my $warn = 0;
+
+if (! -d ".git") {
+ printf "Warning: can't check if file exists, as this is not a git tree";
+ exit 0;
+}

GetOptions(
'fix' => \$fix,
+ 'warn' => \$warn,
'h|help|usage' => \$help,
);

@@ -139,6 +146,8 @@ while (<IN>) {
if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
$broken_ref{$ref}++;
}
+ } elsif ($warn) {
+ print STDERR "Warning: $f references a file that doesn't exist: $fulref\n";
} else {
print STDERR "$f: $fulref\n";
}
--
2.21.0

2019-06-07 18:57:53

by Jonathan Corbet

Subject: Re: [PATCH] docs: Kbuild/Makefile: allow check for missing docs at build time

On Tue, 4 Jun 2019 09:26:27 -0300
Mauro Carvalho Chehab <[email protected]> wrote:

> While this doesn't make sense for production Kernels, in order to
> avoid regressions when documents are touched, let's add a
> check target at the make file.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>

Applied, thanks.

jon