Re: [docs] commands to do "pip install" in docs README file need enhancing

On 8/20/26 4:58 PM, Robert P. J. Day wrote:
> On Thu, 20 Aug 2026, Quentin Schulz wrote:
> 
>> On 8/20/26 3:23 PM, Trevor Gamblin via lists.yoctoproject.org wrote:
>>> On Thu Aug 20, 2026 at 7:20 AM EDT, Robert P. J. Day wrote:
>>>>
>>>>     I just went through this with another Sphinx-based documentation
>>>> repo -- installation instructions that advise the reader to install
>>>> Python modules with "pip install" fail on my Debian 13 system with:
>>>>
>>>>
>>>> $ pip install sphinx-lint
>>>> error: externally-managed-environment
>>>>
>>>> × This environment is externally managed
>>>> ╰─> To install Python packages system-wide, try apt install
>>>>       python3-xyz, where xyz is the package you are trying to
>>>>       install.
>>>>
>>>>       If you wish to install a non-Debian-packaged Python package,
>>>>       create a virtual environment using python3 -m venv path/to/venv.
>>>>       Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
>>>>       sure you have python3-full installed.
>>>>
>>>>       If you wish to install a non-Debian packaged Python application,
>>>>       it may be easiest to use pipx install xyz, which will manage a
>>>>       virtual environment for you. Make sure you have pipx installed.
>>>>
>>>>       See /usr/share/doc/python3.13/README.venv for more information.
>>>>
>>>> note: If you believe this is a mistake, please contact your Python
>>>> installation or OS distribution provider. You can override this, at
>>>> the risk of breaking your Python installation or OS, by passing
>>>> --break-system-packages.
>>>> hint: See PEP 668 for the detailed specification.
>>>>
>>>>
>>>>     Yes, there are solutions, such as using "pipx" instead of "pip", and
>>>> what have you, but it seems that the README file should be augmented
>>>> with an explanation as to how to deal with the above given that the
>>>> "pip install" commands are, in some cases, guaranteed to fail.
>>>
>>> Creating a venv like the error suggests (or via uv) is simple enough and IMO
>>> best practice for anything like this. You could submit a change to provide
>>> short
>>> examples, even replacing the references to pipenv earlier in the file.
>>
>> It's not that simple (though not that difficult). A venv by default
>> is completely isolated and doesn't use anything from the host. The
>> issue is that by doing so, you won't be able to build the docs, only
>> run sphinx-lint, which isn't ideal. You should probably reuse the
>> same venv as documented in
>> documentation/tools/host_packages_scripts/pip3_docs.sh instead.
>>
>> You probably want to update the instructions for Vale as well. We
>> still support pipenv though, via documentation/Pipfile as far as I
>> remember, so that's another option. Maybe add something in
>> dev-packages for example. No clue, I don't use pipenv.
> 
>    i just *knew* i would regret asking that question but since this
> absolutely *needs* to be resolved so that the instructions in the
> README work, here's one solution.
> 
>    forget about venvs (at least for now). the only two packages that

It's what we tell the user to do to build the docs.

> need installation to run the executable commands sphinx-lint and vale
> are the packages with the same names, and they are special cases since
> their purpose is to supply those commands, so the simple solution is
> to install using "pipx", which is designed precisely for that purpose.
> 
>    one can install pipx with pip, then follow that with:
> 
>    $ pipx install sphinx-lint
>    $ pipx install vale
> 
> and it all now works just fine on debian 13. maybe down the road get

Does it? I tried from within a container. First it tells me the path 
pipx installed to isn't in PATH so it won't be available. Then it tells 
me to run pipx ensurepath, which I do, and it then asks me to logoff or 
source ~/.bashrc. Only then do i have sphinx-lint. What a pain. Then I 
follow our instructions and install the sphinx packages in a venv:

sh ./documentation/tools/host_packages_scripts/pip3_docs.sh

I then source the venv:

. yocto-docs-venv/bin/activate

and then I run

make sphinx-lint

and you don't have sphinx-lint available. So you either build the docs, 
or run the linter, but not both without doing some gymnastics...

> fancier with "uv" or whatever but the above will just work, no?
> 

The tool needs to be available in the package feed of all supported 
distros for us to consider using it I think. I wouldn't want to document 
installing uv via pip and going into venv inceptions.

How about:

"""
diff --git a/documentation/Pipfile b/documentation/Pipfile
index 67fce078d..737f8bcea 100644
--- a/documentation/Pipfile
+++ b/documentation/Pipfile
@@ -4,6 +4,8 @@ url = "https://pypi.org/simple"
  verify_ssl = true

  [dev-packages]
+vale = "*"
+sphinx-lint = "*"

  [packages]
  sphinx = "*"
diff --git a/documentation/README b/documentation/README
index 4701357c3..5a90ad0ca 100644
--- a/documentation/README
+++ b/documentation/README
@@ -127,19 +127,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 +149,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
  ============================================================

"""

Cheers,
Quentin