Re: [PATCH] docs/doc-guide: Add documentation on SPHINX_IMGMATH

[Akira Yokosawa <akiyks@gmail.com>]

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@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Cc: Randy Dunlap <rdunlap@infradead.org>
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@gmail.com/
> 
>         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