mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-09-15 06:49:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

README: update instructions for installing vale and sphinx-lint

Browse Source 
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/
(From yocto-docs rev: fe46d5de41930a2762a9ad2543d50e0f4e10463b)

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
Link: https://patch.msgid.link/20260821-pipenv-vale-sphinx-lint-v1-1-f108b7e3e739@cherry.de
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 9955b0f099b6b42a9750f0d544944a2d8e5a39b2)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
This commit is contained in:
Quentin Schulz
2026-08-21 10:25:18 +02:00
committed by Paul Barker
parent 23ecb8d810
commit b70aeb3af5
2 changed files with 19 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
documentation/Pipfile
View File

@@ -4,6 +4,8 @@ url = "https://pypi.org/simple"
verify_ssl = true verify_ssl = true
[dev-packages] [dev-packages]
sphinx-lint = "*"
vale = "*"
[packages] [packages]
sphinx = "*" sphinx = "*"

27
documentation/README
View File

@@ -151,6 +151,13 @@ dependencies in a virtual environment:
$ pipenv install $ pipenv install
$ pipenv run make html $ 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 Style checking the Yocto Project documentation
============================================== ==============================================
@@ -159,19 +166,19 @@ to validate the text style.
To install Vale: To install Vale:
$ pip install vale $ pipenv install --dev
To run Vale: To run Vale:
$ make stylecheck $ pipenv run make stylecheck
Style checking the whole documentation might take some time and generate a 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 lot of warnings/errors, thus one can run Vale on a subset of files or
directories: directories:
$ make stylecheck VALEDOCS=<file> $ pipenv run make stylecheck VALEDOCS=<file>
$ make stylecheck VALEDOCS="<file1> <file2>" $ pipenv run make stylecheck VALEDOCS="<file1> <file2>"
$ make stylecheck VALEDOCS=<dir> $ pipenv run make stylecheck VALEDOCS=<dir>
Lint checking the Yocto Project documentation 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: To install sphinx-lint:
$ pip install sphinx-lint $ pipenv install --dev
To run sphinx-lint: To run sphinx-lint:
$ make sphinx-lint $ pipenv run make sphinx-lint
Lint checking the whole documentation might take some time and generate a 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 lot of warnings/errors, thus one can run sphinx-lint on a subset of files
or directories: or directories:
$ make sphinx-lint SPHINXLINTDOCS=<file> $ pipenv run make sphinx-lint SPHINXLINTDOCS=<file>
$ make sphinx-lint SPHINXLINTDOCS="<file1> <file2>" $ pipenv run make sphinx-lint SPHINXLINTDOCS="<file1> <file2>"
$ make sphinx-lint SPHINXLINTDOCS=<dir> $ pipenv run make sphinx-lint SPHINXLINTDOCS=<dir>
Sphinx theme and CSS customization Sphinx theme and CSS customization
================================== ==================================