lkml.org 
[lkml]   [2022]   [Aug]   [19]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer
From
On Thu, 18 Aug 2022 11:22:24 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> 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@gmail.com>
>> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>> ---
>> 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

\
 
 \ /
  Last update: 2022-08-19 15:52    [W:0.455 / U:0.180 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site