Commit e8939222 authored by Jani Nikula's avatar Jani Nikula Committed by Jonathan Corbet
Browse files

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: default avatarJani Nikula <jani.nikula@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 8d73c512

Documentation/Makefile

+4 −0
Original line number Diff line number Diff line
@@ -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'

Makefile

+2 −1
Original line number Diff line number Diff line
@@ -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 $@

scripts/documentation-file-ref-check

0 → 100755
+15 −0
Original line number Diff line number Diff line 
#!/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

CRA Git | Maintained and supported by SUSTech CRA and CCSE