On Fri, 16 Sep 2022 19:08:05 +0900, Akira Yokosawa wrote:
> Now that building html docs with math expressions does not need texlive
> packages, remove the note on the requirement in the "Sphinx Install"
> section.
>
> Instead, add sections of "Math Expressions in HTML" and "Choice of Math
> Renderer".
> Describe the effect of setting SPHINX_IMGMATH in the latter section.
>
> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>
> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Gentle ping.
Jon, is there anything I need to do for improving this?
Thanks, Akira
> ---
> Hi,
>
> This is a follow-up of the mathjax patch set [1].
> In the thread, I mentioned my plan to add support of SVG images for
> imgmath in reply to Randy.
>
> I've not convinced myself if adding code for checking dvisvgm's
> dependencies in conf.py is the right thing to do.
>
> My reservation comes from:
>
> 1) Any lack in dependency list can result in false-positive of
> enabling SVG and a build error of htmldocs with cryptic looking
> error messages.
> 2) Dependency of dvisvgm may change in future releases of Sphinx
> and/or dvisvgm as well as other texlive packages.
>
> So I'm sending this documentation update describing the current state
> of affairs for the 6.1 merge window.
>
> I might change my mind and revisit the SVG part if I hear people's
> interests in it.
>
> For the moment, SVG math images can be enabled by adding:
>
> SPHINXOPTS="-D imgmath_image_format='svg'"
>
> to the "make htmldocs" command line.
>
> [1]: https://lore.kernel.org/all/9b8ff6d7-e97a-c03f-7d46-4b80ae3cf196@xxxxxxxxx/
>
> Thanks, Akira
> --
> Documentation/doc-guide/sphinx.rst | 57 +++++++++++++++++++++++++++---
> 1 file changed, 53 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index 1228b85f6f77..c708cec889af 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -48,10 +48,6 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
> on the Sphinx version, it should be installed separately,
> with ``pip install sphinx_rtd_theme``.
>
> - #) Some ReST pages contain math expressions. Due to the way Sphinx works,
> - those expressions are written using LaTeX notation. It needs texlive
> - installed with amsfonts and amsmath in order to evaluate them.
> -
> In summary, if you want to install Sphinx version 2.4.4, you should do::
>
> $ virtualenv sphinx_2.4.4
> @@ -86,6 +82,27 @@ Depending on the distribution, you may also need to install a series of
> ``texlive`` packages that provide the minimal set of functionalities
> required for ``XeLaTeX`` to work.
>
> +Math Expressions in HTML
> +------------------------
> +
> +Some ReST pages contain math expressions. Due to the way Sphinx works,
> +those expressions are written using LaTeX notation.
> +There are two options for Sphinx to render math expressions in html output.
> +One is an extension called `imgmath`_ which converts math expressions into
> +images and embeds them in html pages.
> +The other is an extension called `mathjax`_ which delegates math rendering
> +to JavaScript capable web browsers.
> +The former was the only option for pre-6.1 kernel documentation and it
> +requires quite a few texlive packages including amsfonts and amsmath among
> +others.
> +
> +Since kernel release 6.1, html pages with math expressions can be built
> +without installing any texlive packages. See `Choice of Math Renderer`_ for
> +further info.
> +
> +.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
> +.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
> +
> .. _sphinx-pre-install:
>
> Checking for Sphinx dependencies
> @@ -164,6 +181,38 @@ To remove the generated documentation, run ``make cleandocs``.
> as well would improve the quality of images embedded in PDF
> documents, especially for kernel releases 5.18 and later.
>
> +Choice of Math Renderer
> +-----------------------
> +
> +Since kernel release 6.1, mathjax works as a fallback math renderer for
> +html output.\ [#sph1_8]_
> +
> +Math renderer is chosen depending on available commands as shown below:
> +
> +.. table:: Math Renderer Choices for HTML
> +
> + ============= ================= ============
> + Math renderer Required commands Image format
> + ============= ================= ============
> + imgmath latex, dvipng PNG (raster)
> + mathjax
> + ============= ================= ============
> +
> +The choice can be overridden by setting an environment variable
> +``SPHINX_IMGMATH`` as shown below:
> +
> +.. table:: Effect of Setting ``SPHINX_IMGMATH``
> +
> + ====================== ========
> + Setting Renderer
> + ====================== ========
> + ``SPHINX_IMGMATH=yes`` imgmath
> + ``SPHINX_IMGMATH=no`` mathjax
> + ====================== ========
> +
> +.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8.
> +
> +
> Writing Documentation
> =====================
>
>
> base-commit: 7ebeef22dcc2c3db83dcd1e8292744cf29c1859f
