All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] docs/doc-guide: Add documentation on SPHINX_IMGMATH
@ 2022-09-16 10:08 Akira Yokosawa
  2022-09-27  2:10 ` Akira Yokosawa
  0 siblings, 1 reply; 3+ messages in thread
From: Akira Yokosawa @ 2022-09-16 10:08 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Randy Dunlap, Akira Yokosawa,
	Mauro Carvalho Chehab, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 3+ messages in thread

* Re: [PATCH] docs/doc-guide: Add documentation on SPHINX_IMGMATH
  2022-09-16 10:08 [PATCH] docs/doc-guide: Add documentation on SPHINX_IMGMATH Akira Yokosawa
@ 2022-09-27  2:10 ` Akira Yokosawa
  2022-09-29 19:14   ` Jonathan Corbet
  0 siblings, 1 reply; 3+ messages in thread
From: Akira Yokosawa @ 2022-09-27  2:10 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Randy Dunlap, Mauro Carvalho Chehab,
	linux-doc, linux-kernel, Akira Yokosawa

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

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] docs/doc-guide: Add documentation on SPHINX_IMGMATH
  2022-09-27  2:10 ` Akira Yokosawa
@ 2022-09-29 19:14   ` Jonathan Corbet
  0 siblings, 0 replies; 3+ messages in thread
From: Jonathan Corbet @ 2022-09-29 19:14 UTC (permalink / raw)
  To: Akira Yokosawa
  Cc: Mauro Carvalho Chehab, Randy Dunlap, Mauro Carvalho Chehab,
	linux-doc, linux-kernel, Akira Yokosawa

Akira Yokosawa <akiyks@gmail.com> writes:

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

Nope, just need to wait for me to recover from the fall European tour...
applied now, thanks.

jn

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2022-09-29 19:14 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-09-16 10:08 [PATCH] docs/doc-guide: Add documentation on SPHINX_IMGMATH Akira Yokosawa
2022-09-27  2:10 ` Akira Yokosawa
2022-09-29 19:14   ` Jonathan Corbet

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.