[Documentation Bug] Install Instructions don't work

[maltfield]

This ticket is a bug report in the documentation of the rinohtype module on pypi.

• https://pypi.org/project/rinohtype/

Installation is trivial:

pip install rinohtype

...

rinoh CHANGES.rst

Unfortunatley, installation is obviously not so trivial, as attempting to follow the above documentation produces an error.

Problem

The following execution uses docker to consistantly reproduce the error in Debian 12

sudo apt-get install docker.io
sudo bash -c 'gpasswd -a "${SUDO_USER}" docker'
su - `whoami`

docker run --rm -it --entrypoint /bin/bash debian:bookworm-slim

apt update
apt install python3 python3-sphinx python3-pip

pip install rinohtype
rinoh CHANGES.rst

Example

Below is an example exeuction of the above commands

user@disp3666:~$ sudo apt-get install docker.io
...
user@disp3666:~$ 

user@disp3666:~$ sudo bash -c 'gpasswd -a "${SUDO_USER}" docker'
Adding user user to group docker
user@disp3666:~$ 

user@disp3666:~$ su - `whoami`
user@disp3666:~$ 

user@disp3666:~$ docker run --rm -it --entrypoint /bin/bash debian:bookworm-slim
Unable to find image 'debian:bookworm-slim' locally
bookworm-slim: Pulling from library/debian
5c32499ab806: Pull complete 
Digest: sha256:7e490910eea2861b9664577a96b54ce68ea3e02ce7f51d89cb0103a6f9c386e0
Status: Downloaded newer image for debian:bookworm-slim
root@b3f9a2a1eadb:/# 

root@b3f9a2a1eadb:/# apt update
...
Get:1 http://deb.debian.org/debian bookworm InRelease [151 kB]
Get:2 http://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
Get:3 http://deb.debian.org/debian-security bookworm-security InRelease [48.0 kB]
Get:4 http://deb.debian.org/debian bookworm/main amd64 Packages [8791 kB]
Get:5 http://deb.debian.org/debian bookworm-updates/main amd64 Packages [6924 B]
Get:6 http://deb.debian.org/debian-security bookworm-security/main amd64 Packages [281 kB]
Fetched 9333 kB in 14s (644 kB/s)                                              
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
All packages are up to date.
root@b3f9a2a1eadb:/# 

root@b3f9a2a1eadb:/# apt install python3 python3-sphinx python3-pip
...
0 upgraded, 206 newly installed, 0 to remove and 0 not upgraded.
Need to get 148 MB of archives.
After this operation, 599 MB of additional disk space will be used.
Do you want to continue? [Y/n] y
...
root@b3f9a2a1eadb:/# 

root@b3f9a2a1eadb:/# pip install rinohtype
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.11/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.
root@b3f9a2a1eadb:/# 

root@b3f9a2a1eadb:/# rinoh CHANGES.rst
bash: rinoh: command not found
root@b3f9a2a1eadb:/# 

Solution

The documentation should be updated such that a user following it can install and use rinoh, without erorrs.

[brechtm]

Hi Michael,

The installation instructions now indeed assume that the user is familiar with Python. It would be good to mention that it would be best to create a virtual environment where rinohtype (and Sphinx) can be installed into (this is also what is suggested by the error in your report). I'm thinking about linking to https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments for further information about virtual environments.

Do you think this would be sufficient?

[maltfield]

Sorry, I do not think that a valid solution to this is anything where a user copy-and-pasting the commands from the documentation results in anything other than rinoh being properly installed and useable

This issue is further less trivial for the rinohtype users because sphinx-build on Debian hard-codes the aboslute path to the python binary in its shebang, which means that -- even if the venv were created with --system-site-packages and the user is currently inside the activated (source /path/to/venv/bin/activate) venv -- trying to use sphinx-build -b rinoh will jump outside the venv where rinoh is installed, and again throw the Builder name rinoh not registered or available through entry point error).

[maltfield]

I think a reasonable solution would be to change this line from the documentation:

pip install rinohtype

To this:

python3 -m virtualenv /tmp/python-venv --system-site-packages
source /tmp/python-venv/bin/activate

pip install rinohtype Sphinx

[maltfield]

A better long-term solution to this is to work with the Debian maintainers, so users can install rinohtype in apt:

• https://github.com/brechtm/rinohtype/issues/451

[brechtm]

Sorry, I do not think that a valid solution to this is anything where a user copy-and-pasting the commands from the documentation results in anything other than rinoh being properly installed and useable

This issue is further less trivial for the rinohtype users because sphinx-build on Debian hard-codes the aboslute path to the python binary in its shebang, which means that -- even if the venv were created with --system-site-packages and the user is currently inside the activated (source /path/to/venv/bin/activate) venv -- trying to use sphinx-build -b rinoh will jump outside the venv where rinoh is installed, and again throw the Builder name rinoh not registered or available through entry point error).

I see. Packaging remains to be a bit of an issue in the Python world. Especially if you're not familiar with Python, I can imagine. I'm assuming you happen to be in this situation? Welcome to the jungle! 🐒

Personally, I don't think it makes sense to try and repackage each and every Python package as a native package for a Linux package manager. Sure, I can see that it's convenient, but imagine all the time spent to maintain this huge amount of packages (and versions) when nowadays installing packages into a Python virtual environment is simple and works reliably. This has the added advantage that you can install different versions of packages alongside each-other and avoid dependency conflicts since a virtual environment only has those dependencies installed for a single project.

For command-line tools like Sphinx and rinoh, one could argue that you'd want these to be installed to a location in PATH. You can consider using pipx for this (yet another tool!). However, for Sphinx, I would recommend setting up a virtualenv by means of Poetry or uv (yes, yet more tools!) to manage the dependencies (Sphinx itself, rinohtype and any other extensions). This way, it's easy for collaborators to install all dependencies required for building the docs of your project.

I think a reasonable solution would be to change this line from the documentation [...] To this:

python3 -m virtualenv /tmp/python-venv --system-site-packages
source /tmp/python-venv/bin/activate

pip install rinohtype Sphinx

As you already noticed, --system-site-packages causes issues in this case. I recommend simply installing all needed dependencies in the virtual environment.

The problem with trying to provide full installation instructions is: where do I draw the line? The source command you provided works for bash, but what about macOS users who are on zsh by default? The furthest I would go is this:

python3 -m venv .venv
# activate the venv (ref docs)
pip install rinohtype

Yes, it's suboptimal, but I cannot condense all the intricacies in a few lines.

[maltfield]

I don't think it makes sense to try and repackage each and every Python package as a native package for a Linux package manager.

I'd argue this is not the case. Pip is horribly insecure.

It's much more secure to install python modules with apt than pip, due to the fact that pip doesn't verify the authenticity of anything that it downloads with cryptographic signatures. This means that, unlike apt (which has required authenticating everything it downloads since 2005), it is safer to obtain python modules with apt than with pip.

I recommend simply installing all needed dependencies in the virtual environment.

For the security reasons explianed above, the fewer dependencies installed with pip, the better.

[maltfield]

The furthest I would go is this:

python3 -m venv .venv
# activate the venv (ref docs)
pip install rinohtype

I would appreciate this as a big improvement, but is it possible to do this instead?

python3 -m venv .venv
# activate the venv (ref docs)
pip install rinohtype Sphinx

...where ref docs is a hyperlink to the relevant python virtualenv documentation?