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
