Re: Expectation to --no-pdf option (was Re: [PATCH v2 0/5] Address some issues with sphinx detection)

[Akira Yokosawa <akiyks@gmail.com>]

On Sat, 9 Jul 2022 08:59:46 +0100,
Mauro Carvalho Chehab wrote:
> Em Sat, 9 Jul 2022 08:01:02 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> [-CC: ksummit-discuss]
>> On Sat, 9 Jul 2022 00:27:25 +0900, Akira Yokosawa wrote:
>>> On Fri, 8 Jul 2022 15:59:10 +0100,
>>> Mauro Carvalho Chehab wrote:  
>>>> Em Fri, 08 Jul 2022 08:02:52 -0600
>>>> Jonathan Corbet <corbet@lwn.net> escreveu:
>>>>  
>>>>> Akira Yokosawa <akiyks@gmail.com> writes:
>>>>>  
>>>>>> In my tests, the mathjax extension works with all the versions of Sphinx
>>>>>> I tested (1.7.9, 2.4.4, 3.4.3 (debian bullseye), 4.2.0 (openSUSE LEAP 15.4),
>>>>>> and 5.0.2).
>>>>>> Note that math expressions should look much sharper (vector fonts)
>>>>>> than those from imgmath (pixel images).
>>>>>> The time for a browser to complete the rendering might be longer than
>>>>>> with imgmath, especially for pages with a lot of math expressions,
>>>>>> though.  (Yes, I see some of media documents have a lot of them.)
>>>>>>
>>>>>> When you are detached from network connections, browsers will give
>>>>>> up and show those expressions in mathjax source code.   
>>>>  
>>>>> -extensions.append("sphinx.ext.imgmath")
>>>>> +extensions.append("sphinx.ext.mathjax")  
>>>>
>>>> There are two problems with this:
>>>>
>>>> 1. mathjax doesn't work for PDF output - nor would work if we add support
>>>>    for man pages some day;  
>>>
>>> Hmm, if I understand what is written in the following page:
>>>     https://www.sphinx-doc.org/en/master/usage/extensions/math.html
>>>
>>> , both imgmath and mathjax extensions are relevant only for HTML output.
>>>
>>> It says:
>>>
>>>     Changed in version 1.8: Math support for non-HTML builders is integrated
>>>     to sphinx-core. So mathbase extension is no longer needed.
>>>
>>> When did you see the issue of "mathjax doesn't work for PDF output" ?  
>>
>> For the record,
>>
>> I tested mathjax and PDF output with Sphinx 1.7.9, whose latex mode
>> can't handle nested tables.
>> I had no problem in building userspace-api.pdf and math expressions
>> in it look perfect.
>>
>> So I believe mathjax does not affect PDF output.
> 
> Did you also test epubdocs?
No, I didn't.

Now I see that mathjax doesn't work with epubdocs.

I think I found a means to use mathjax only for htmldocs.
It is mentioned in an issue at Sphinx:

    https://github.com/sphinx-doc/sphinx/issues/3740#issuecomment-385503305

Actually, it turns out that the mathjax extension is loaded by default
since Sphinx 1.8.  A simple assignment in conf.py can enable it:

    html_math_renderer = 'mathjax'

As a matter of fact, it can be enabled via the SPHINXOPTS make variable.

Just try this against current docs-next:

    make SPHINXDIRS=userspace-api SPHINXOPTS="-D html_math_renderer='mathjax'" htmldocs

> 
> It was an issue when we decided to use imgmath. If this got fixed for
> both supported non-html outputs, we can start using mathjax and get
> rid of installing latex and dvipng.

As far as I know, ebook readers don't understand javascript and mathjax
doesn't work. imgmath is mandatory for epub.

> 
>> Mauro wrote:
>>> As imgmath works everywere, we opted to use it instead. We were
>>> actually hoping that the lack of proper math support on Sphinx were
>>> something that later Sphinx versions after 1.3.1 would have fixed.   
>>
>> I'm not going to test earlier versions of Sphinx and I have no idea
>> of what issue Mauro saw at the time, but it sounds to me the issue
>> has been fixed since.
> 
> Good.

I'm suspecting now that pdfdocs had no issue with mathjax, but I'm not sure.

>  
>>>   
>>>> 2. Some Kernel developers disable javascript.  
>>> OK, mathjax has no chance, then...  
>>
>> On the second thought, I think mathjax (latex-free "make htmldocs")
>> is good enough for test build purposes.  When javascript is disabled,
>> math expressions are rendered in mathjax source.
> 
> Hmm... are there a way to use it with javascript disabled? 

No chance. Javascript is a must for mathjax.

>                                                            If so, maybe
> we can force it to always render math expressions during the build, instead
> or relying on javascript at exec time.
> 
>> As conf.py is programmable, it is possible to choose sphinx.ext.imgmath
>> when dvipng is found on the build system.
> 
> Not sure I like the idea. This would actually mean in practice that
> all developers that are currently doing doc builds will keep using
> imgmath, because they all have it already installed.

The purpose here is to get more developers who actually run "make htmldocs"
on their (not limited to) documentation changes.  Difference of math rendering
doesn't matter much.

One possible improvement for imgmath is to use its SVG format option, which
uses dvisvgm instead.  It will provide scalable math expressions similar to
those provided by mathjax.  Of course you need properly working dvisvgm.

> 
>> As for sphinx-pre-install, what about adding an option
>>
>>     --no-js   For those who disable javascript in their browser.
>>
>> which provide the list of required packages for dvipng?
> 
> It is not that simple.
> 
> Sphinx has a configurable theme engine. On our builds, we're using
> since the beginning the RTD (readthedocs) theme as default, but
> recent versions default to classic if sphinx_rtd_theme package is
> not installed.
> 
> All themes I know that provide a search button use JS to implement
> such feature.
> 
> So, a "--no-js" won't provide a javascript-free build environment.
I see.

What about "--imgmath" ? 

> 
> -
> 
> On a side discussion, should we keep recommending the install of 
> sphinx_rtd_theme? It is not mandatory anymore to have it installed,
> and the theme is more a matter of personal preferences. 
> 
> Also, when testing or modifying the docs, the theme doesn't really
> matter.
> 
> So, IMHO, we could stop recommending it.
I agree.

        Thanks, Akira

> 
> Regards,
> Mauro