summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
diff options
context:
space:
mode:
authorAkira Yokosawa <akiyks@gmail.com>2022-08-27 13:37:18 +0900
committerJonathan Corbet <corbet@lwn.net>2022-09-27 13:21:43 -0600
commit6b0d3e7c5888d2ec0f5527ee699265dc852a5faa (patch)
tree28ea7d09e3edba24bddf796eb79453b356b4fea2 /Documentation/conf.py
parent20e21951f3ebceac93168854edc1c222e515d292 (diff)
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: Akira Yokosawa <akiyks@gmail.com> Acked-by: Mauro 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: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/conf.py')
-rw-r--r--Documentation/conf.py27
1 files changed, 26 insertions, 1 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..f12eb51235da 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]
@@ -106,7 +118,20 @@ 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'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']