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

[Petr Vorel]

> > On 3/31/25 19:53, Petr Vorel wrote:
> > > > 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.
> > The thing is that readthedoc is already doing "pip install sphinx" before
> > building the website, so any other "pip install sphinx" or "pip install
> > requirements.txt" (with sphinx in it) won't create issues. pip will check
> > the cache, finding sphinx already installed and it will skip its
> > installation.

> > The only thing we should avoid is the usage of sphinx version. So we just
> > keep "sphinx" as a generic package inside requirements.txt and pip will take
> > care about the version.

> Of course we have to *not* version also sphinx-rtd-theme, because it's release
> is tight to sphinx version. That was obvious (2.0.0 requires sphinx < 8), but I
> tried it in our readthedocs.org to verify it really fails.

> IMHO it'd be better to keep sphinx and sphinx-rtd-theme to these which are used
> in readthedocs.org. Because that way we still use the same version (we control
> the version used in readthedocs.org via os version used in .readthedocs.yml.

I missed the main point for using the same sphinx version for development and
for the real docs in readthedocs.org: we get changes tested (both in CI job and
hopefully with development) if we use the same version. Because different
version can have incompatibilities which we discover once it gets broken on
readthedocs.org :(.

Kind regards,
Petr

> Kind regards,
> Petr

> > > 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
> > Andrea