On Mon, Oct 09, 2017 at 03:26:15PM +0000, Jani Nikula wrote:
> 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@xxxxxxxxx>
> ---
> Documentation/Makefile | 4 ++++
> Makefile | 2 +-
> scripts/documentation-file-ref-check | 15 +++++++++++++++
> 3 files changed, 20 insertions(+), 1 deletion(-)
> create mode 100755 scripts/documentation-file-ref-check
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 85f7856f0092..f4f5aecb81d1 100644
> --- 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 cf007a31d575..a97e70a9a39c 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1454,7 +1454,7 @@ $(help-board-dirs): help-%:
>
> # Documentation targets
> # ---------------------------------------------------------------------------
> -DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs linkcheckdocs
> +DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs linkcheckdocs 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
> index 000000000000..bc1659900e89
> --- /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
> --
> 2.11.0
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
I just did something similar, but in python (parallel even). I like
your version for its elegant simplicity.
I do however have a series of doc ref fixes ready to send out. They are
fairly fine-grained but could easily be squashed down.
Given that you added this check - do you also have a patch for fixes?
Regards,
--Tom
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
