mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Reorganize documentation of the imgmath configuration variables
This commit is contained in:
jfbu
parent
505ff622c2
commit
da3763170e
@ -30,74 +30,21 @@ This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG
|
|||||||
images. This of course means that the computer where the docs are built must
|
images. This of course means that the computer where the docs are built must
|
||||||
have both programs available.
|
have both programs available.
|
||||||
|
|
||||||
There are various config values you can set to influence how the images are
|
There are various configuration values you can set to influence how the images
|
||||||
built:
|
are built:
|
||||||
|
|
||||||
.. confval:: imgmath_image_format
|
.. confval:: imgmath_image_format
|
||||||
|
|
||||||
The output image format. The default is ``'png'``. It should be either
|
The output image format. The default is ``'png'``. It should be either
|
||||||
``'png'`` or ``'svg'``.
|
``'png'`` or ``'svg'``. The image is produced by first executing ``latex``
|
||||||
|
on the TeX mathematical mark-up then (depending on the requested format)
|
||||||
.. confval:: imgmath_latex
|
either `dvipng`_ or `dvisvgm`_.
|
||||||
|
|
||||||
The command name with which to invoke LaTeX. The default is ``'latex'``; you
|
|
||||||
may need to set this to a full path if ``latex`` is not in the executable
|
|
||||||
search path.
|
|
||||||
|
|
||||||
Since this setting is not portable from system to system, it is normally not
|
|
||||||
useful to set it in ``conf.py``; rather, giving it on the
|
|
||||||
:program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
|
|
||||||
option should be preferable, like this::
|
|
||||||
|
|
||||||
sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
|
|
||||||
|
|
||||||
This value should only contain the path to the latex executable, not further
|
|
||||||
arguments; use :confval:`imgmath_latex_args` for that purpose.
|
|
||||||
|
|
||||||
.. confval:: imgmath_dvipng
|
|
||||||
|
|
||||||
The command name with which to invoke ``dvipng``. The default is
|
|
||||||
``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in
|
|
||||||
the executable search path. This option is only used when
|
|
||||||
``imgmath_image_format`` is set to ``'png'``.
|
|
||||||
|
|
||||||
.. confval:: imgmath_dvisvgm
|
|
||||||
|
|
||||||
The command name with which to invoke ``dvisvgm``. The default is
|
|
||||||
``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not
|
|
||||||
in the executable search path. This option is only used when
|
|
||||||
``imgmath_image_format`` is ``'svg'``.
|
|
||||||
|
|
||||||
.. confval:: imgmath_latex_args
|
|
||||||
|
|
||||||
Additional arguments to give to latex, as a list. The default is an empty
|
|
||||||
list.
|
|
||||||
|
|
||||||
.. confval:: imgmath_latex_preamble
|
|
||||||
|
|
||||||
Additional LaTeX code to put into the preamble of the short LaTeX files that
|
|
||||||
are used to translate the math snippets. This is empty by default. Use it
|
|
||||||
e.g. to add more packages whose commands you want to use in the math.
|
|
||||||
|
|
||||||
.. confval:: imgmath_dvipng_args
|
|
||||||
|
|
||||||
Additional arguments to give to dvipng, as a list. The default value is
|
|
||||||
``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
|
|
||||||
image a bit darker and larger then it is by default, and produces PNGs with a
|
|
||||||
transparent background. This option is used only when
|
|
||||||
``imgmath_image_format`` is ``'png'``.
|
|
||||||
|
|
||||||
.. confval:: imgmath_dvisvgm_args
|
|
||||||
|
|
||||||
Additional arguments to give to dvisvgm, as a list. The default value is
|
|
||||||
``['--no-fonts']``. This option is used only when ``imgmath_image_format``
|
|
||||||
is ``'svg'``.
|
|
||||||
|
|
||||||
.. confval:: imgmath_use_preview
|
.. confval:: imgmath_use_preview
|
||||||
|
|
||||||
``dvipng`` and ``dvisvgm`` have the ability to collect from LaTeX the
|
``dvipng`` and ``dvisvgm`` both have the ability to collect from LaTeX the
|
||||||
"depth" of the rendered text: an inline image should use this "depth" in a
|
"depth" of the rendered math: an inline image should use this "depth" in a
|
||||||
``vertical-align`` style to be correctly aligned with surrounding text.
|
``vertical-align`` style to get correctly aligned with surrounding text.
|
||||||
|
|
||||||
This mechanism requires the `LaTeX preview package`_ (available as
|
This mechanism requires the `LaTeX preview package`_ (available as
|
||||||
``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this
|
``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this
|
||||||
@ -117,6 +64,67 @@ built:
|
|||||||
The font size (in ``pt``) of the displayed math. The default value is
|
The font size (in ``pt``) of the displayed math. The default value is
|
||||||
``12``. It must be a positive integer.
|
``12``. It must be a positive integer.
|
||||||
|
|
||||||
|
.. confval:: imgmath_latex
|
||||||
|
|
||||||
|
The command name with which to invoke LaTeX. The default is ``'latex'``; you
|
||||||
|
may need to set this to a full path if ``latex`` is not in the executable
|
||||||
|
search path.
|
||||||
|
|
||||||
|
Since this setting is not portable from system to system, it is normally not
|
||||||
|
useful to set it in ``conf.py``; rather, giving it on the
|
||||||
|
:program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
|
||||||
|
option should be preferable, like this::
|
||||||
|
|
||||||
|
sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
|
||||||
|
|
||||||
|
This value should only contain the path to the latex executable, not further
|
||||||
|
arguments; use :confval:`imgmath_latex_args` for that purpose.
|
||||||
|
|
||||||
|
.. confval:: imgmath_latex_args
|
||||||
|
|
||||||
|
Additional arguments to give to latex, as a list. The default is an empty
|
||||||
|
list.
|
||||||
|
|
||||||
|
.. confval:: imgmath_latex_preamble
|
||||||
|
|
||||||
|
Additional LaTeX code to put into the preamble of the LaTeX files used to
|
||||||
|
translate the math snippets. This is left empty by default. Use it
|
||||||
|
e.g. to add packages which modify the fonts used for math, such as
|
||||||
|
``'\\usepackage{newtxsf}'`` for sans-serif fonts, or
|
||||||
|
``'\\usepackage{fouriernc}'`` for serif fonts. Indeed, the default LaTeX
|
||||||
|
math fonts have rather thin glyphs which (in HTML output) often do not
|
||||||
|
match well with the font for text.
|
||||||
|
|
||||||
|
.. confval:: imgmath_dvipng
|
||||||
|
|
||||||
|
The command name to invoke ``dvipng``. The default is
|
||||||
|
``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in
|
||||||
|
the executable search path. This option is only used when
|
||||||
|
``imgmath_image_format`` is set to ``'png'``.
|
||||||
|
|
||||||
|
.. confval:: imgmath_dvipng_args
|
||||||
|
|
||||||
|
Additional arguments to give to dvipng, as a list. The default value is
|
||||||
|
``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
|
||||||
|
image a bit darker and larger then it is by default (this compensates
|
||||||
|
somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a
|
||||||
|
transparent background. This option is used only when
|
||||||
|
``imgmath_image_format`` is ``'png'``.
|
||||||
|
|
||||||
|
.. confval:: imgmath_dvisvgm
|
||||||
|
|
||||||
|
The command name to invoke ``dvisvgm``. The default is
|
||||||
|
``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not
|
||||||
|
in the executable search path. This option is only used when
|
||||||
|
``imgmath_image_format`` is ``'svg'``.
|
||||||
|
|
||||||
|
.. confval:: imgmath_dvisvgm_args
|
||||||
|
|
||||||
|
Additional arguments to give to dvisvgm, as a list. The default value is
|
||||||
|
``['--no-fonts']``, which means that ``dvisvgm`` will render glyphs as path
|
||||||
|
elements (cf the `dvisvgm FAQ`_). This option is used only when
|
||||||
|
``imgmath_image_format`` is ``'svg'``.
|
||||||
|
|
||||||
|
|
||||||
:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
|
:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
|
||||||
-------------------------------------------------------
|
-------------------------------------------------------
|
||||||
@ -217,6 +225,7 @@ package jsMath_. It provides this config value:
|
|||||||
|
|
||||||
.. _dvipng: https://savannah.nongnu.org/projects/dvipng/
|
.. _dvipng: https://savannah.nongnu.org/projects/dvipng/
|
||||||
.. _dvisvgm: https://dvisvgm.de/
|
.. _dvisvgm: https://dvisvgm.de/
|
||||||
|
.. _dvisvgm FAQ: https://dvisvgm.de/FAQ
|
||||||
.. _MathJax: https://www.mathjax.org/
|
.. _MathJax: https://www.mathjax.org/
|
||||||
.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
|
.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
|
||||||
.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html
|
.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user