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

[Jonathan Corbet]

Akira Yokosawa <akiyks@xxxxxxxxx> 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@xxxxxxxxx>
> Acked-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>
> ---
> 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