Documentation: add script and build target to check for broken file references

Add a simple script and build target to do a treewide grep for
references to files under Documentation, and report the non-existing
file in stderr. It tries to take into account punctuation not part of
the filename, and wildcards, but there are bound to be false positives
too. Mostly seems accurate though.

We've moved files around enough to make having this worthwhile.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 5e65fa5c6ab7ea08c4c944600ab64bbc6e39d632..2ca77ad0f2388c24f5954bc328437c431476c202 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -97,6 +97,9 @@ endif # HAVE_SPHINX
 # The following targets are independent of HAVE_SPHINX, and the rules should
 # work or silently pass without Sphinx.
 
+refcheckdocs:
+       $(Q)cd $(srctree);scripts/documentation-file-ref-check
+
 cleandocs:
        $(Q)rm -rf $(BUILDDIR)
        $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
@@ -109,6 +112,7 @@ dochelp:
        @echo  '  epubdocs        - EPUB'
        @echo  '  xmldocs         - XML'
        @echo  '  linkcheckdocs   - check for broken external links (will connect to external hosts)'
+       @echo  '  refcheckdocs    - check for references to non-existing files under Documentation'
        @echo  '  cleandocs       - clean all generated files'
        @echo
        @echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'

diff --git a/Makefile b/Makefile
index bcb20d2c1eac2da2baa770957a5e81c7a31c0b06..11df924e160a6c90c006b69ae96c7b53a51e5ea1 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -1454,7 +1454,8 @@ $(help-board-dirs): help-%:
 
 # Documentation targets
 # ---------------------------------------------------------------------------
-DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs linkcheckdocs dochelp
+DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
+              linkcheckdocs dochelp refcheckdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
        $(Q)$(MAKE) $(build)=Documentation $@

diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check
new file mode 100755 (executable)
index 0000000..bc16599
--- /dev/null
+++ b/scripts/documentation-file-ref-check
@@ -0,0 +1,15 @@
+#!/bin/sh
+# Treewide grep for references to files under Documentation, and report
+# non-existing files in stderr.
+
+for f in $(git ls-files); do
+       for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do
+               # presume trailing . and , are not part of the name
+               ref=${ref%%[.,]}
+
+               # use ls to handle wildcards
+               if ! ls $ref >/dev/null 2>&1; then
+                       echo "$f: $ref" >&2
+               fi
+       done
+done