lkml.org 
[lkml]   [2022]   [Jul]   [5]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    SubjectRe: [PATCH v2 0/5] Address some issues with sphinx detection
    From
    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

    \
     
     \ /
      Last update: 2022-07-05 06:17    [W:5.289 / U:0.576 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site