On Thu, 7 Jul 2022 21:15:58 +0100, Mauro Carvalho Chehab wrote:
> Em Tue, 5 Jul 2022 13:15:57 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
>
>> Hi Mauro,
>>
[...]
>> So this is a meta-level feedback considering the most likely uses
>> of sphinx-pre-install.
>>
>> I think first-time users of sphinx-pre-install are more likely
>> interested in getting ready for running "make html". They won't
>> bother with "make pdfdocs".
>
> True, but, as you're pointing below, math expressions require LaTeX.
>
> The idea of using --no-pdf is to setup an environment without LaTeX,
> meaning that math tags would only be partially parsed: basically, the
> output would be html with LaTeX-like math expressions (at least last
> time I tried).
Oh, that is your intention. :-/
When I saw this help text in "./scripts/sphinx-pre-install --help":
--no-pdf - don't check for dependencies required to build PDF docs
for the first time, my expectation was like this:
If I make "./scripts/sphinx-pre-install --no-pdf" happy, "make htmldocs"
will complete without any warning on package requirements.
But I got this warning from "make htmldocs" among others:
WARNING: dvipng command 'dvipng' cannot be run (needed for math display), check the imgmath_dvipng setting
And my reaction to it was something like:
"What!!! Why sphinx-pre-install didn't complain?"
"OK. I'll ignore sphinx-pre-install. Let's see what I need to install."
The reason why this mismatch has never surfaced as a problem is, I suppose,
because most people don't use --no-pdf at all.
However, in thinking of making --no-pdf the default, I thought --no-pdf
should be more trustworthy.
If your goal is to provide LaTeX-free packages for "make htmldocs",
the option should have been named --no-latex or similar (probably in
addition to --no-pdf), no?
Well, arguing does not help. I stop here.
More constructive approach would be to make "make htmldocs" be
truly latex-free. Then --no-pdf and --no-latex will be equivalent.
Fortunately, it is possible by using the mathjax extension instead of
imgmath. With mathjax, rendering of math expressions is delegated to
web browsers.
The resulting HTML will depend on mathjax code and math fonts from
somewhere in the cloud (by default, https://cdnjs.cloudflare.com/ajax/libs/mathjax/...
or https://cdn.jsdelivr.net/npm/mathjax@3/... depending on the Sphinx
version).
All you need is this one-liner:
--------
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..fe1084510329 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -106,7 +106,7 @@ else:
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 2
-extensions.append("sphinx.ext.imgmath")
+extensions.append("sphinx.ext.mathjax")
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
--------
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.
Mauro, wouldn't this approach work for you?
Thanks, Akira
PS: Replies to the other topics will be sent separately.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. Pulling in a bunch of JavaScript from the net while browsing the kernel docs is not an entirely pleasing solution either. But perhaps it's preferable to loading the system with Latex. I kind of wish we could just do without the fancy math processing entirely, but I lost that battle some time ago...:) Mauro, have you looked at that option? Thanks, jon
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;
2. Some Kernel developers disable javascript.
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.
>
> Pulling in a bunch of JavaScript from the net while browsing the kernel
> docs is not an entirely pleasing solution either. But perhaps it's
> preferable to loading the system with Latex.
If we could change conf.py to either load either one depending if it is
building PDF or not would be the best. The technical problem is that the
javascript solution is not compatible with PDF output.
> I kind of wish we could
> just do without the fancy math processing entirely, but I lost that
> battle some time ago...:)
The media uAPI book uses math, and also vm/memory-model.rst. The last
one could easily use just a C code.
yet, it sounds funny to not have it used inside DRM. GPU processing
does lots of math. i would expect to have math used there for things
similar to the usages on media.
Trying to describe the colorspace conversion expressions there without
math would be really painful:
https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/colorspaces-details.html?highlight=detailed+colorspace
Anyway, if you have some other solution, I'd gladly use something else.
>
> Mauro, have you looked at that option?
Yes, but it got discarded due to pdf output. Not sure if this would work
on epub either.
>
> Thanks,
>
> jon
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" ?
> 2. Some Kernel developers disable javascript.
OK, mathjax has no chance, then...
Thanks, Akira
[-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.
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.
>
>> 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.
As conf.py is programmable, it is possible to choose sphinx.ext.imgmath
when dvipng is found on the build system.
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?
Thoughts?
Some comforting news for Jon:
Jon wrote:
> Pulling in a bunch of JavaScript from the net while browsing the kernel
> docs is not an entirely pleasing solution either. But perhaps it's
> preferable to loading the system with Latex.
With Sphinx >=4.0, mathjax is loaded only when a page with math expressions
is opened. Sphinx is improving in this regard.
Thanks, Akira
>
> Thanks, Akira
>
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
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
© 2016 - 2026 Red Hat, Inc.