Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <d0e1a08a-b965-ada6-e026-4e1cc38fbd90@gmail.com>
Date:   Tue, 5 Jul 2022 13:15:57 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.9.1
To:     Mauro Carvalho Chehab <mchehab@kernel.org>
Cc:     corbet@lwn.net, ksummit-discuss@lists.linuxfoundation.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        mchehab+huawei@kernel.org, Akira Yokosawa <akiyks@gmail.com>
References: <cover.1656756450.git.mchehab@kernel.org>
Subject: Re: [PATCH v2 0/5] Address some issues with sphinx detection
Content-Language: en-US
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <cover.1656756450.git.mchehab@kernel.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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