| Message ID | 20241031-add-bblock-documentation-v1-2-32b89093bbda@baylibre.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Add bblock documentation | expand |
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
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: + + $ make sphinx-lint SPHINXLINTDOCS=<file> + $ make sphinx-lint SPHINXLINTDOCS="<file1> <file2>" + $ make sphinx-lint SPHINXLINTDOCS=<dir> + Sphinx theme and CSS customization ==================================
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(-)