linux-kernel - Re: [PATCH v3 1/2] docs/conf.py: Treat mathjax as fallback math renderer

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <87edwzoujt.fsf@meer.lwn.net>
Date:   Mon, 29 Aug 2022 10:59:02 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Akira Yokosawa <akiyks@...il.com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Cc:     linux-doc@...r.kernel.org,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH v3 1/2] docs/conf.py: Treat mathjax as fallback math
 renderer

Akira Yokosawa <akiyks@...il.com> writes:

> Currently, math expressions using the "math::" directive or
> the ":math:" role of Sphinx need the imgmath extension for proper
> rendering in html and epub builds.
> imgmath requires dvipng (and latex).
> Otherwise, "make htmldocs" will complain of missing commands.
>
> As a matter of fact, the mathjax extension is loaded by default since
> Sphinx v1.8 and it is good enough for html docs without any dependency
> on texlive packages.
>
> Stop loading the imgmath extension for html docs unless requirements
> for imgmath are met.
>
> To find out whether required commands are available, add a helper
> find_command(), which is a wrapper of shutil.which().
>
> For epub docs, keep the same behavior of always loading imgmath.
>
> Signed-off-by: Akira Yokosawa <akiyks@...il.com>
> Acked-by: Mauro Carvalho Chehab <mchehab@...nel.org>
> ---
> Changes since v2:
>  - Mention find_command() in the changelog.
>  - Simplify find_command() by using shutil.which().
>
> Changes sinve v1:
>  - Acked-by from Mauro
> --
>  Documentation/conf.py | 29 ++++++++++++++++++++++++++++-
>  1 file changed, 28 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 255384d094bf..c4aaedd96220 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -15,6 +15,18 @@
>  import sys
>  import os
>  import sphinx
> +import shutil
> +
> +# helper
> +# ------
> +
> +def have_command(cmd):
> +    """Search ``cmd`` in the ``PATH`` environment.
> +
> +    If found, return True.
> +    If not found, return False.
> +    """
> +    return shutil.which(cmd) is not None
>  
>  # Get Sphinx version
>  major, minor, patch = sphinx.version_info[:3]
> @@ -107,7 +119,22 @@ else:
>  autosectionlabel_prefix_document = True
>  autosectionlabel_maxdepth = 2
>  
> -extensions.append("sphinx.ext.imgmath")
> +# Load math renderer:
> +# For html builder, load imgmath only when its dependencies are met.
> +# mathjax is the default math renderer since Sphinx 1.8.
> +have_latex =  have_command('latex')
> +have_dvipng = have_command('dvipng')
> +load_imgmath = ((have_latex and have_dvipng)
> +                or (major == 1 and minor < 8)
> +                or 'epub' in sys.argv)
> +
> +if load_imgmath:
> +    extensions.append("sphinx.ext.imgmath")
> +    math_renderer = 'imgmath'
> +else:
> +    math_renderer = 'mathjax'
> +
> +sys.stderr.write("math_renderer: %s\n" % math_renderer)

I've taken this line out as I applied the patch.  The docs build is
verbose enough as it is, and this line isn't really going to add
anything for most people.  If it needs to be there, I think, it should
only show up on a V=1 build.

Thanks,

jon