Em Sat, 9 Jul 2022 08:01:02 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> 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@xxxxxxx> escreveu:
> >>
> >>> Akira Yokosawa <akiyks@xxxxxxxxx> 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
