From b70aeb3af5a866b2299a273b099b6ca0abb99ae3 Mon Sep 17 00:00:00 2001 From: Quentin Schulz Date: Fri, 21 Aug 2026 10:25:18 +0200 Subject: [PATCH] README: update instructions for installing vale and sphinx-lint pip install won't work on recent Debian distros (and Debian-based ones I'm assuming as well) and will suggest using pipx instead. In any case, pip and pipx aren't actually that user-friendly to us for the simple reason the instructions to build the documentation, c.f. documentation/tools/host_packages_scripts/pip3_docs.sh, make use of a virtual environment which doesn't have access to the host system's Python modules (missing --system-site-packages). So you would need to chose between building the docs and running vale/sphinx-lint but not both at the same time. Instead, update the instructions to use pipenv for stylecheck and sphinx-lint make targets such that there's a setup in which one can build the docs AND run those commands without doing some back and forth between venvs or host packages and the venv. Reported-by: Robert P. J. Day Closes: https://lore.kernel.org/yocto-docs/959e65b6-e7eb-bcc3-992f-bed7276c8449@crashcourse.ca/ (From yocto-docs rev: fe46d5de41930a2762a9ad2543d50e0f4e10463b) Signed-off-by: Quentin Schulz Link: https://patch.msgid.link/20260821-pipenv-vale-sphinx-lint-v1-1-f108b7e3e739@cherry.de Signed-off-by: Antonin Godard (cherry picked from commit 9955b0f099b6b42a9750f0d544944a2d8e5a39b2) Signed-off-by: Antonin Godard Signed-off-by: Paul Barker --- documentation/Pipfile | 2 ++ documentation/README | 27 +++++++++++++++++---------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/documentation/Pipfile b/documentation/Pipfile index 7ee1d22905..e631741ad6 100644 --- a/documentation/Pipfile +++ b/documentation/Pipfile @@ -4,6 +4,8 @@ url = "https://pypi.org/simple" verify_ssl = true [dev-packages] +sphinx-lint = "*" +vale = "*" [packages] sphinx = "*" diff --git a/documentation/README b/documentation/README index c394ab9288..f498da171e 100644 --- a/documentation/README +++ b/documentation/README @@ -151,6 +151,13 @@ dependencies in a virtual environment: $ pipenv install $ pipenv run make html +Note: if you decide to use Pipenv for installing the dependencies, don't forget +to prefix all the make commands below with "pipenv run ". The make commands +which already start with "pipenv run " don't need to be prefixed a second time +but require you to use Pipenv for them to run and aren't available when +following the instructions from +https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host. + Style checking the Yocto Project documentation ============================================== @@ -159,19 +166,19 @@ to validate the text style. To install Vale: - $ pip install vale + $ pipenv install --dev To run Vale: - $ make stylecheck + $ pipenv run make stylecheck Style checking the whole documentation might take some time and generate a lot of warnings/errors, thus one can run Vale on a subset of files or directories: - $ make stylecheck VALEDOCS= - $ make stylecheck VALEDOCS=" " - $ make stylecheck VALEDOCS= + $ pipenv run make stylecheck VALEDOCS= + $ pipenv run make stylecheck VALEDOCS=" " + $ pipenv run make stylecheck VALEDOCS= Lint checking the Yocto Project documentation ============================================= @@ -181,19 +188,19 @@ the project uses sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint). To install sphinx-lint: - $ pip install sphinx-lint + $ pipenv install --dev To run sphinx-lint: - $ make sphinx-lint + $ pipenv run 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= - $ make sphinx-lint SPHINXLINTDOCS=" " - $ make sphinx-lint SPHINXLINTDOCS= + $ pipenv run make sphinx-lint SPHINXLINTDOCS= + $ pipenv run make sphinx-lint SPHINXLINTDOCS=" " + $ pipenv run make sphinx-lint SPHINXLINTDOCS= Sphinx theme and CSS customization ==================================