commands to do "pip install" in docs README file need enhancing

["Robert P. J. Day" <rpjday@crashcourse.ca>]

[-- Attachment #1: Type: text/plain, Size: 1522 bytes --]


  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.

rday