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

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

[Mauro Carvalho Chehab]

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 <mchehab+samsung@kernel.org>
---

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

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

[Jonathan Corbet]

On Tue,  4 Jun 2019 09:26:27 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> 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 <mchehab+samsung@kernel.org>

Applied, thanks.

jon