[LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

> On 3/31/25 18:37, Petr Vorel wrote:
> > Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
> > good idea to add there sphinx, when it uses containers? I can test it in a
> > separate branch, but we discussed some time ago that we should avoid adding
> > sphinx for readthedocs.

> > Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
> > (the previous proposal).

> > Kind regards,
> > Petr

> I forgot about it. Thanks for remembering. At the moment readthedocs
> installs sphinx via pip, so if we add just sphinx ro requirements.txt
> without version, pip should reinstall the same version which is already
> available before building the website.

> We should give a try and eventually get back to the old way.

To be honest I would prefer to avoid experimenting with readthedoc as much as
possible. How about just forcing 'pip install sphinx' only in Makefile?
It can be the simplest version - without checking if it's installed.

Because I don't see any benefit to add sphinx to readthedocs where it's not
needed - in the best case it will takes time to reinstall, in worst it just take
time to experiment to find it breaks things. We are going to diverge from
readthedocs anyway, unless we manually sync with the sphinx version it uses.
You asked for newest version (which is 8.2.3, if I don't count broken 8.3),
but in readthedocs we use old ubuntu-22.04, which uses sphinx 4.3.2 [1].

We could update to noble (24.04LTS) (if supported by readthedocs) to get newer
7.2.6 (as I can test it as a separate effort.

[1] https://packages.ubuntu.com/jammy/python3-sphinx
[2] https://packages.ubuntu.com/noble/python3-sphinx

I guess controlling the version is important, therefore I would prefer b) or c).

a) simple version in Makefile, without version:

$(VENV_DIR):
	$(PYTHON) -m virtualenv $(VENV_DIR)
	$(VENV_CMD) && pip install sphinx && pip install -r requirements.txt

b) simple version with specifying sphinx version:

SPHINX_VERSION := 8.2.3 # or 7.2.6 or 4.3.2?
...
$(VENV_DIR):
	$(PYTHON) -m virtualenv $(VENV_DIR)
	$(VENV_CMD) && pip install sphinx==$(SPHINX_VERSION) && pip install -r requirements.txt

c) more complicated version (you did not like) which install sphinx only when
needed:

SPHINX_VERSION := 8.2.3
INSTALL_SPHINX := $(shell $(PYTHON) -c "import sphinx" 2>/dev/null && echo ":" || echo "pip install sphinx==$(SPHINX_VERSION)")
...
$(VENV_DIR):
	$(PYTHON) -m virtualenv $(VENV_DIR)
	$(VENV_CMD) && pip install -r requirements.txt && $(INSTALL_SPHINX)

Kind regards,
Petr

> Andrea