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.
For epub docs, keep the same behavior of always loading imgmath.
Signed-off-by: Akira Yokosawa <[email protected]>
Acked-by: Mauro Carvalho Chehab <[email protected]>
---
Changes sinve v1:
- Acked-by from Mauro
--
Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
1 file changed, 33 insertions(+), 1 deletion(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..3ec1f845c839 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -15,6 +15,23 @@
import sys
import os
import sphinx
+from subprocess import check_output
+
+# helper
+# ------
+
+def have_command(cmd, ver_opt, str_in_ver):
+ """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
+ or not.
+ """
+
+ try:
+ ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
+ have_cmd = str_in_ver in ver_str
+ except:
+ have_cmd = False
+
+ return have_cmd
# Get Sphinx version
major, minor, patch = sphinx.version_info[:3]
@@ -106,7 +123,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', '--version', 'pdfTeX')
+have_dvipng = have_command('dvipng', '--version', '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)
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
--
2.25.1
Akira Yokosawa <[email protected]> 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.
>
> For epub docs, keep the same behavior of always loading imgmath.
>
> Signed-off-by: Akira Yokosawa <[email protected]>
> Acked-by: Mauro Carvalho Chehab <[email protected]>
> ---
> Changes sinve v1:
> - Acked-by from Mauro
>
> --
> Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
> 1 file changed, 33 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 934727e23e0e..3ec1f845c839 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -15,6 +15,23 @@
> import sys
> import os
> import sphinx
> +from subprocess import check_output
> +
> +# helper
> +# ------
> +
> +def have_command(cmd, ver_opt, str_in_ver):
> + """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
> + or not.
> + """
> +
> + try:
> + ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
> + have_cmd = str_in_ver in ver_str
> + except:
> + have_cmd = False
> +
> + return have_cmd
So this is adding infrastructure that isn't really mentioned in the
changelog.
A more fundamental comment, though, is that I have learned (the hard
way, repeatedly) that good things do not come from bare "except"
statements. They always hide bugs. If there is an exception you're
worried about here, please list it explicitly.
Otherwise seems good.
Thanks,
jon
On Thu, 18 Aug 2022 11:22:24 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <[email protected]> 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.
>>
>> For epub docs, keep the same behavior of always loading imgmath.
>>
>> Signed-off-by: Akira Yokosawa <[email protected]>
>> Acked-by: Mauro Carvalho Chehab <[email protected]>
>> ---
>> Changes sinve v1:
>> - Acked-by from Mauro
>>
>> --
>> Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
>> 1 file changed, 33 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 934727e23e0e..3ec1f845c839 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -15,6 +15,23 @@
>> import sys
>> import os
>> import sphinx
>> +from subprocess import check_output
>> +
>> +# helper
>> +# ------
>> +
>> +def have_command(cmd, ver_opt, str_in_ver):
>> + """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
>> + or not.
>> + """
>> +
>> + try:
>> + ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
>> + have_cmd = str_in_ver in ver_str
>> + except:
>> + have_cmd = False
>> +
>> + return have_cmd
>
> So this is adding infrastructure that isn't really mentioned in the
> changelog.
Sorry for missing it.
>
> A more fundamental comment, though, is that I have learned (the hard
> way, repeatedly) that good things do not come from bare "except"
> statements. They always hide bugs. If there is an exception you're
> worried about here, please list it explicitly.
I see. Thank you for the insightful tip.
I'm more inclined to use the simpler approach of the "which()" function
defined in sphinx/kfigure.py, which is free of try-except constructs.
Will respin this along with the fix of 2/3 in a couple of days.
Thanks, Akira
>
> Otherwise seems good.
>
> Thanks,
>
> jon