Re: [docs] [PATCH 2/5] documentation: Makefile: add SPHINXLINTDOCS to specify subset to sphinx-lint

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Julien,

On Thu Oct 31, 2024 at 5:56 PM CET, Julien Stephan wrote:
> make sphinx-lint runs sphinx-lint on the whole documentation which can be
> long and reports a lot or errors/warnings. Let's add a new
> SHPINXLINTDOCS variable to allow specifying a subset, just as VALEDOCS
> does. Keep variable assignment aligned and also use $(SOURCEDIR) by
> default for SPHINXLINTDOCS and VALEDOCS variables.
>
> Also update the README file and fix a typo in Link checking section
> title.
>
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
> ---
>  documentation/Makefile | 23 ++++++++++++-----------
>  documentation/README   |  9 ++++++++-
>  2 files changed, 20 insertions(+), 12 deletions(-)
>
> diff --git a/documentation/Makefile b/documentation/Makefile
> index 189bd1dfac69d3b3185aa3a2ff7c212084ae280b..0bd9db5eaeb9122f9f396cda61631c403a1325a0 100644
> --- a/documentation/Makefile
> +++ b/documentation/Makefile
> @@ -3,17 +3,18 @@
>  
>  # You can set these variables from the command line, and also
>  # from the environment for the first two.
> -SPHINXOPTS    ?= -W --keep-going -j auto
> -SPHINXBUILD   ?= sphinx-build
> +SPHINXOPTS     ?= -W --keep-going -j auto
> +SPHINXBUILD    ?= sphinx-build
>  # Release notes are excluded because they contain contributor names and commit messages which can't be modified
> -VALEOPTS      ?= --no-wrap --glob '!migration-guides/release-notes-*.rst'
> -VALEDOCS      ?= .
> -SOURCEDIR     = .
> -IMAGEDIRS     = */svg
> -BUILDDIR      = _build
> -DESTDIR       = final
> -SVG2PNG       = inkscape
> -SVG2PDF       = inkscape
> +VALEOPTS       ?= --no-wrap --glob '!migration-guides/release-notes-*.rst'
> +SOURCEDIR      = .
> +VALEDOCS       ?= $(SOURCEDIR)
> +SPHINXLINTDOCS ?= $(SOURCEDIR)
> +IMAGEDIRS      = */svg
> +BUILDDIR       = _build
> +DESTDIR        = final
> +SVG2PNG        = inkscape
> +SVG2PDF        = inkscape
>  
>  ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
>  $(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed")
> @@ -54,7 +55,7 @@ stylecheck:
>  	vale $(VALEOPTS) $(VALEDOCS)
>  
>  sphinx-lint:
> -	sphinx-lint $(SOURCEDIR)
> +	sphinx-lint $(SPHINXLINTDOCS)
>  
>  epub: $(PNGs)
>  	$(SOURCEDIR)/set_versions.py
> diff --git a/documentation/README b/documentation/README
> index 6a4db97d65b9c23828163d8b548485b2e302bc97..d2676ae2de9cb9c2dbe4191c0e38f8847cd8603b 100644
> --- a/documentation/README
> +++ b/documentation/README
> @@ -149,7 +149,7 @@ lot of warnings/errors, thus one can run Vale on a subset:
>    $ make stylecheck VALEDOCS="<file1> <file2>"
>    $ make stylecheck VALEDOCS=<dir>
>  
> -Link checking the Yocto Project documentation
> +Lint checking the Yocto Project documentation
>  =============================================
>  
>  To fix errors which are not reported by Sphinx itself,
> @@ -163,6 +163,13 @@ To run sphinx-lint:
>  
>   $ make sphinx-lint
>  
> +Lint checking the whole documentation might take some time and generate a
> +lot of warnings/errors, thus one can run sphinx-lint on a specific file:

s/on a specific file:/on a subset of files or directories:/

> +
> +  $ make sphinx-lint SPHINXLINTDOCS=<file>
> +  $ make sphinx-lint SPHINXLINTDOCS="<file1> <file2>"
> +  $ make sphinx-lint SPHINXLINTDOCS=<dir>
> +
>  Sphinx theme and CSS customization
>  ==================================
>  

Cheers,
Antonin

--
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com