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

[Quentin Schulz <quentin.schulz@cherry.de>]

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.

Cheers,
Quentin