diff mbox series

README: update instructions for installing vale and sphinx-lint

Message ID 20260821-pipenv-vale-sphinx-lint-v1-1-f108b7e3e739@cherry.de
State New
Headers show
Series README: update instructions for installing vale and sphinx-lint | expand

Commit Message

Quentin Schulz Aug. 21, 2026, 8:25 a.m. UTC 
From: Quentin Schulz <quentin.schulz@cherry.de>

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 <rpjday@crashcourse.ca>
Closes: https://lore.kernel.org/yocto-docs/959e65b6-e7eb-bcc3-992f-bed7276c8449@crashcourse.ca/
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 documentation/Pipfile |  2 ++
 documentation/README  | 27 +++++++++++++++++----------
 2 files changed, 19 insertions(+), 10 deletions(-)


---
base-commit: 3660b8085a5e790c1ea8bf75236fff4b216fe19c
change-id: 20260821-pipenv-vale-sphinx-lint-296f93ab8386

Best regards,
--  
Quentin Schulz <quentin.schulz@cherry.de>
diff mbox series

Patch

diff --git a/documentation/Pipfile b/documentation/Pipfile
index 67fce078d..f415cbf3f 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 4701357c3..a3301b662 100644
--- a/documentation/README
+++ b/documentation/README
@@ -119,6 +119,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
 ==============================================
 
@@ -127,19 +134,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=<file>
-  $ make stylecheck VALEDOCS="<file1> <file2>"
-  $ make stylecheck VALEDOCS=<dir>
+  $ pipenv run make stylecheck VALEDOCS=<file>
+  $ pipenv run make stylecheck VALEDOCS="<file1> <file2>"
+  $ pipenv run make stylecheck VALEDOCS=<dir>
 
 Lint checking the Yocto Project documentation
 =============================================
@@ -149,19 +156,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=<file>
-  $ make sphinx-lint SPHINXLINTDOCS="<file1> <file2>"
-  $ make sphinx-lint SPHINXLINTDOCS=<dir>
+  $ pipenv run make sphinx-lint SPHINXLINTDOCS=<file>
+  $ pipenv run make sphinx-lint SPHINXLINTDOCS="<file1> <file2>"
+  $ pipenv run make sphinx-lint SPHINXLINTDOCS=<dir>
 
 Checking for broken links in the Yocto Project documentation
 ============================================================