[Documentation] Broken Install & Quickstart Guide (Builder name rinoh not registered or available through entry point)

[maltfield]

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

• https://www.mos6581.oarg/rinohtype/master/install.html

rinohtype supports Python 3.3 and up. Use pip to install the latest version of rinohtype and its dependencies:

pip install rinohtype

If you plan on using rinohtype as an alternative to LaTeX, you will want to install Sphinx as well:

pip install Sphinx

And

• https://www.mos6581.org/rinohtype/master/quickstart.html

sphinx-build -b rinoh . _build/rinoh

Unfortunatley, following the documentation does not work.

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

mkdir docs
cd docs
sphinx-quickstart -q -p test -a test

sphinx-build -b rinoh . _build/rinoh

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:/# mkdir docs
root@b3f9a2a1eadb:/# 

root@b3f9a2a1eadb:/# cd docs
root@b3f9a2a1eadb:/docs# 

root@b3f9a2a1eadb:/docs# sphinx-quickstart -q -p test -a test

Finished: An initial directory structure has been created.

You should now populate your master file /docs/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

root@b3f9a2a1eadb:/docs# 

root@b3f9a2a1eadb:/docs# sphinx-build -b rinoh . _build/rinoh
Running Sphinx v5.3.0

Sphinx error:
Builder name rinoh not registered or available through entry point
root@b3f9a2a1eadb:/docs# 

Solution

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