Re: [PATCH] docs: Makefile: Add a testdocs target for the documentation unit tests

[Randy Dunlap <rdunlap@infradead.org>]

On 9/16/26 11:41 AM, Kees Cook wrote:
> tools/unittests/run.py discovers and runs the unit tests there (which
> are primarily documentation tools), but nothing in the build calls it,
> so the tests are only run by whoever remembers that the script is there.

Now if we can just remember that this target is present/available ;)

> Give it a target, next to the other checks that need no Sphinx. The name
> ends in "docs", so it matches the "%docs" pattern already in
> no-dot-config-targets and runs without a configured tree, and it sets
> PYTHONPYCACHEPREFIX as the other Python targets here do, to keep
> __pycache__ directories out of the source tree.
> 
>   $ make testdocs
>   ...
>   Ran 121 tests
> 
> with "make dochelp" listing it between refcheckdocs and cleandocs.
> 
> Tested with GNU Make 4.4.1 and Python 3.14.7, on a tree with no .config,
> where it ran 121 tests and left no __pycache__ behind.
> 
> Assisted-by: LLM
> Signed-off-by: Kees Cook <kees@kernel.org>
> ---
> I debated the naming here, since "tools/unittests/" is such a general
> directory location, but figured I'd start with a target that made the most
> logical sense given what is actually being tested there? I dunno. Maybe
> "make testtools"? But that reads weird.

I'm happy with "make testdocs".

Ran 122 tests in 0.241s

Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Makefile               | 2 +-
>  Documentation/Makefile | 5 +++++
>  2 files changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/Makefile b/Makefile
> index 66654fa71655..88557288163d 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2002,7 +2002,7 @@ $(help-board-dirs): help-%:
>  # ---------------------------------------------------------------------------
>  DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
>  	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs mandocs \
> -	       htmldocs-redirects
> +	       htmldocs-redirects testdocs
>  
>  PHONY += $(DOC_TARGETS)
>  $(DOC_TARGETS):
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 377a449656c8..ee852afe9bb9 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -74,6 +74,10 @@ htmldocs-redirects: $(srctree)/Documentation/.renames.txt
>  refcheckdocs:
>  	$(Q)cd $(srctree); tools/docs/documentation-file-ref-check
>  
> +testdocs:
> +	$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
> +		$(PYTHON3) $(srctree)/tools/unittests/run.py
> +
>  cleandocs:
>  	$(Q)rm -rf $(BUILDDIR)
>  
> @@ -95,6 +99,7 @@ dochelp:
>  	@echo  '                    (will connect to external hosts)'
>  	@echo  '  refcheckdocs    - check for references to non-existing files under'
>  	@echo  '                    Documentation'
> +	@echo  '  testdocs        - run the unit tests of the documentation tools'
>  	@echo  '  cleandocs       - clean all generated files'
>  	@echo
>  	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'

thanks.
-- 
~Randy