Hi Mauro,
On Sat, 2 Jul 2022 11:11:24 +0100, Mauro Carvalho Chehab wrote:
> Checking if Sphinx is available and read to run is tricky, and may involve
> installing several packages for the document build to happen.
>
> There are two options to install Sphinx:
>
> - via distro-provided packages;
> - via pip, using virtualenv/venv.
>
> Some recent discussions showed a couple of misleading instructions.
>
> This series improves the Sphinx detection by:
>
> - Fixing the logich with checks if a past venv is working and recommend
> just enabling it instead of installing a new venv;
> - Detect if sphinx-build stopped working on a venv. This may happen during
> distribution updates;
> - Move the PDF minimal version to be later, in order for it to be printed only
> after finishing the Sphinx version check;
>
> Additionally, as now the Sphinx provided on almost all modern distros are
> above the minimal required version, place instructions about how to install
> Sphinx from the distro-provided packages after placing the instructions for
> installing it via venv.
>
> This will hopefully help to have more developers checking documentation
> builds with
>
> make htmldocs
So this is a meta-level feedback considering the most likely uses
of sphinx-pre-install.
I think first-time users of sphinx-pre-install are more likely
interested in getting ready for running "make html". They won't
bother with "make pdfdocs". They won't likely be interested in
virtualenv, either.
So I think it would be reasonable to change the default behavior
of sphinx-pre-install.
I mean the reasonable behavior without any option would be that of
when both --no-pdf and --no-virtualenv are given to the current
version.
There are a few issues on --no-pdf.
It says imagemagick and gcc are necessary, but they are redundant
in "make html", as far as I see.
Furthermore, it doesn't check dvipng and latex, which are used
for generating math equation images in HTML.
Fedora, RHEL/CentOS, and openSUSE Leap provide helpful packages
for installing math expression support.
Fedora 36 python3-sphinx-latex (python3-sphinx depends on this)
RHEL 9/CentOS stream 9 ditto
openSUSE Leap 15.4 python3-Sphinx_4_2_0-latex
(python3-Sphinx_4_2_0 depends on this) or
python3-Sphinx-latex
(python3-Sphinx depends on this, version: 2.3.1)
Other distros, whose texlive packages are coarse grained, don't provide
such helper packages.
Also, as mentioned previously, RHEL 9/CentOS stream9's texlive-xecjk
doesn't work at the moment due to the lack of its dependency (texlive-ctex).
I opened a bug ticket at RedHat bugzilla:
https://bugzilla.redhat.com/show_bug.cgi?id=2086254
Unfortunately, I've heard no response yet.
If you know some means to boost its priority, please provide a comment
or two to the ticket.
Until the issue can be resolved, "make pdfdocs" is limited to non-CJK
build on CentOS stream 9, RHEL 9 and its clones if you must stick to
distro packages. For non-CJK build to work, you must not have
google-noto-sans-cjk-ttc-fonts.
openSUSE Leap does not support full CJK build of "make pdfdocs", either.
Its Noto font packaging is peculiar and a similar named package of
noto-sans-cjk-fonts installs a set of language-specific fonts, each
of which doesn't qualify as a CJK font.
Seeing these problems of LTS distros, I'd suggest sphinx-pre-install
--pdf would check packages for non-CJK builds.
Another option of --cjk would show you additional packages for full CJK build.
TL;DR, my suggestion of options and defaults to sphinx-pre-install:
--no-pdf (default): for htmldocs only
--no-virtualenv (default): distro Sphinx package
(mention --virtualenv if distro Sphinx package is too young)
--virtualenv: Sphinx by venv/virtualenv
--pdf: for pdfdocs
--no-cjk (default): don't bother with CJK pdfdocs
--cjk: for CJK pdfdocs
(print warning if user's distro doesn't support CJK)
Thoughts?
Thanks, Akira
>
> ---
>
> v2:
> - Fix some issues at the logic that was recommending installing via
> distro-package manager;
> - Add a notice about Sphinx 3.0+ false-positive warnings due to a
> Sphinx bug. People using a version different than the recommended
> one should know about that.
>
> Mauro Carvalho Chehab (5):
> scripts: sphinx-pre-install: fix venv version check logic
> scripts: sphinx-pre-install: report broken venv
> scripts: sphinx-pre-install: check for PDF min version later on
> scripts: sphinx-pre-install: provide both venv and package installs
> scripts: sphinx-pre-install: place a warning for Sphinx >= 3.0
>
> scripts/sphinx-pre-install | 90 +++++++++++++++++++++++++++++---------
> 1 file changed, 69 insertions(+), 21 deletions(-)
>
> --
> 2.36.1
