Commit 6b0d3e7c authored by Akira Yokosawa's avatar Akira Yokosawa Committed by Jonathan Corbet

docs/conf.py: Treat mathjax as fallback math renderer

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: default avatarAkira Yokosawa <akiyks@gmail.com>
Acked-by: default avatarMauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/a6a877fc-dc93-2bda-a6d3-37001d99942a@gmail.com
[jc: Took out the writing of the math_renderer decision]
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 20e21951
...@@ -15,6 +15,18 @@ ...@@ -15,6 +15,18 @@
import sys import sys
import os import os
import sphinx 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 # Get Sphinx version
major, minor, patch = sphinx.version_info[:3] major, minor, patch = sphinx.version_info[:3]
...@@ -106,7 +118,20 @@ else: ...@@ -106,7 +118,20 @@ else:
autosectionlabel_prefix_document = True autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 2 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'
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment