On Thu, 18 Aug 2022 11:22:24 -0600, Jonathan Corbet wrote:
> 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.
>>
>> 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 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
