From 12c0c4105864a23361083b978ad19cbef7c7b82e Mon Sep 17 00:00:00 2001
From: Julien Stephan <jstephan@baylibre.com>
Date: Mon, 4 Nov 2024 16:59:13 +0100
Subject: [PATCH] documentation: Makefile: add SPHINXLINTDOCS to specify subset
 to sphinx-lint

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.

(From yocto-docs rev: ae46746897361d4177f3c4284f46753e3aa8c3c3)

Signed-off-by: Julien Stephan <jstephan@baylibre.com>
Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>
Tested-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 3dfe7b5c746af31de74f67cf88214e5d52bdb65d)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>
---
 documentation/Makefile | 23 ++++++++++++-----------
 documentation/README   | 10 +++++++++-
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/documentation/Makefile b/documentation/Makefile
index 4e0af4bd30..580688d543 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)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/documentation/README b/documentation/README
index a7138c40e2..d7428eb8ed 100644
--- a/documentation/README
+++ b/documentation/README
@@ -173,7 +173,7 @@ directories:
   $ 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,
@@ -187,6 +187,14 @@ 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 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
 ==================================