linux-toradex.git/scripts/sphinx-pre-install, branch v6.9-rc7

docs: drop the version constraints for sphinx and dependencies

2024-03-03T15:17:20+00:00

As discussed (see Links), there is some inertia to move to the recent
Sphinx versions for the doc build environment.

As first step, drop the version constraints and the related comments. As
sphinx depends on jinja2, jinja2 is pulled in automatically. So drop that.
Then, the sphinx-pre-install script will fail though with:

  Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305.

The script simply expects to parse a version constraint with Sphinx in the
requirements.txt. That version is used in the script for suggesting the
virtualenv directory name.

To suggest a virtualenv directory name, when there is no version given in
the requirements.txt, one could try to guess the version that would be
downloaded with 'pip install -r Documentation/sphinx/requirements.txt'.
However, there seems no simple way to get that version without actually
setting up the venv and running pip. So, instead, name the directory with
the fixed name 'sphinx_latest'.

Finally update the Sphinx build documentation to reflect this directory
name change.

Link: https://lore.kernel.org/linux-doc/874jf4m384.fsf@meer.lwn.net/
Link: https://lore.kernel.org/linux-doc/20240226093854.47830-1-lukas.bulwahn@gmail.com/
Reviewed-by: Akira Yokosawa 
Tested-by: Vegard Nossum 
Signed-off-by: Lukas Bulwahn 
Signed-off-by: Jonathan Corbet 
Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>

docs: scripts: sphinx-pre-install: Fix building docs with pyyaml package

2024-02-14T22:32:03+00:00

The Python module pyyaml is required to build the docs, but it is only
listed in Documentation/sphinx/requirements.txt and is therefore missing
when Sphinx is installed as a package and not via pip/pypi.

Add pyyaml as an optional package for multiple distros to fix building the
docs if you prefer to install Sphinx as a package.

Signed-off-by: Thorsten Blum 
Reviewed-by: Vegard Nossum 
Tested-by: Vegard Nossum 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240208205550.984-1-thorsten.blum@toblux.com

docs: sphinx-pre-install fix-noto-sans-cjk on fedora

2024-01-30T21:00:30+00:00

fedora 38 and later changed the directory and package name that
provides NotoSansCJK-Regular.ttc. this adds the new search path and
suggests the correct package if on fedora 38 or later.

Signed-off-by: Andrew Ballance 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240124043918.31771-1-andrewjballance@gmail.com

docs: Raise the minimum Sphinx requirement to 2.4.4

2023-12-15T15:36:33+00:00

Commit 31abfdda6527 (docs: Deprecate use of Sphinx < 2.4.x) in 6.2 added a
warning that support for older versions of Sphinx would be going away.
There have been no complaints, so the time has come.  Raise the minimum
Sphinx version to 2.4.4 and clean out some compatibility code that we no
longer need.

Reviewed-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net
Signed-off-by: Jonathan Corbet

docs: sphinx-pre-install: don't require the RTD theme

2022-10-13T17:14:43+00:00

We don't default to the RTD theme anymore, so sphinx-pre-install need not
insist on installing it.

Acked-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

scripts: sphinx-pre-install: place a warning for Sphinx >= 3.0

2022-07-07T18:47:34+00:00

Newer versions of Sphinx have a known bug:
	https://github.com/sphinx-doc/sphinx/pull/8313

Those currently produces 11 false-positive warnings On Sphinx
version 3.1+.

While Sphinx fix is not applied, let's warn adventurers that would
be using Sphinx installed via distro packages.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/085e0ada65c11da9303d07e70c510dc45f21315b.1656756450.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet

scripts: sphinx-pre-install: provide both venv and package installs

2022-07-07T18:47:34+00:00

As it is not a consensus about installing sphinx using venv, and
modern distributions are now shipping with Sphinx versions above
the minimal requirements to build the docs, provide both venv
and package install commands by default.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/7c99d985df204c73e3daafd5fd2f30a31269405d.1656756450.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet

scripts: sphinx-pre-install: check for PDF min version later on

2022-07-07T18:47:34+00:00

Better to add the PDF note late for venv recommendation.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/8e117aabe6dfa1b1ec92dccd20e801393c977667.1656756450.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet

scripts: sphinx-pre-install: report broken venv

2022-07-07T18:47:10+00:00

After distro upgrades, the directory names for python may change.
On such case, the previously-created venv will be broken, and
sphinx-build won't run.

Add a logic to report it.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/f117f03555b0636d2be0b68f3a23b1d3f03ccf1d.1656756450.git.mchehab@kernel.org
[jc: fixed typo in warning message]
Signed-off-by: Jonathan Corbet

scripts: sphinx-pre-install: fix venv version check logic

2022-07-07T18:45:32+00:00

The logic which checks if the venv version is good enough
but was not activated is broken: it is checking against
the wrong val, making it to recommend to re-create a venv
every time. Fix it.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/afe01b7863fd655986d84ace8948f3d7aede796d.1656756450.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet