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

[Mauro Carvalho Chehab <mchehab@kernel.org>]

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?

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.

> 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.
 
> >   
> >> 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? 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.

> 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.

-

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.

Regards,
Mauro