From c45f962b05106d91d64d9fa820a3951b694d9a6a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 29 Jul 2019 01:35:50 +0900 Subject: [PATCH 1/6] Fix #6620: i18n: classifiers of definition list are not translated with docutils-0.15 --- CHANGES | 2 ++ sphinx/util/nodes.py | 3 +++ 2 files changed, 5 insertions(+) diff --git a/CHANGES b/CHANGES index 4595a44b5..adeb8ad04 100644 --- a/CHANGES +++ b/CHANGES @@ -58,6 +58,8 @@ Bugs fixed * #6549: sphinx-build: Escaped characters in error messages * #6545: doctest comments not getting trimmed since Sphinx 1.8.0 * #6561: glossary: Wrong hyperlinks are generated for non alphanumeric terms +* #6620: i18n: classifiers of definition list are not translated with + docutils-0.15 Testing -------- diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py index abbc432df..52e43c2e2 100644 --- a/sphinx/util/nodes.py +++ b/sphinx/util/nodes.py @@ -133,6 +133,9 @@ def apply_source_workaround(node: Element) -> None: node.source = definition_list_item.source node.line = definition_list_item.line - 1 node.rawsource = node.astext() # set 'classifier1' (or 'classifier2') + elif isinstance(node, nodes.classifier) and not node.source: + # docutils-0.15 fills in rawsource attribute, but not in source. + node.source = node.parent.source if isinstance(node, nodes.image) and node.source is None: logger.debug('[i18n] PATCH: %r to have source, line: %s', get_full_module_name(node), repr_domxml(node)) From 1adf12bfa71fe6ba2304ba2c96c06627eef7161b Mon Sep 17 00:00:00 2001 From: jfbu Date: Tue, 16 Apr 2019 16:43:08 +0200 Subject: [PATCH 2/6] Make imgmath_use_preview work also for svg output --- doc/usage/extensions/math.rst | 5 +-- sphinx/ext/imgmath.py | 44 +++++++++++++++++++++++--- sphinx/templates/imgmath/preview.tex_t | 2 +- 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index a3dba8aac..1c64c5d17 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -106,8 +106,9 @@ built: installed (on Ubuntu xenial, it is available as `preview-latex-style`_). Therefore, the default for this option is ``False``. - Currently this option is only used when ``imgmath_image_format`` is - ``'png'``. + .. versionchanged:: 2.1.0 + + This option can also be used with ``imgmath_image_format`` set to ``'svg'``. .. confval:: imgmath_add_tooltips diff --git a/sphinx/ext/imgmath.py b/sphinx/ext/imgmath.py index 327be8973..6d007407a 100644 --- a/sphinx/ext/imgmath.py +++ b/sphinx/ext/imgmath.py @@ -87,6 +87,25 @@ DOC_BODY_PREVIEW = r''' ''' depth_re = re.compile(br'\[\d+ depth=(-?\d+)\]') +depthsvg_re = re.compile(br'.*, depth=(.*)pt') + + +def read_svg_depth(filename): + # type: (str) -> int + """Read the depth from comment at last line of SVG file + """ + with open(filename, 'r') as f: + for line in f: + pass + return int(line[11:-4]) + + +def write_svg_depth(filename, depth): + # type: (str, int) -> None + """Write the depth to SVG file as a comment at end of file + """ + with open(filename, 'a') as f: + f.write('\n' % depth) def generate_latex_macro(math: str, config: Config, confdir: str = '') -> str: @@ -95,6 +114,7 @@ def generate_latex_macro(math: str, config: Config, confdir: str = '') -> str: 'fontsize': config.imgmath_font_size, 'baselineskip': int(round(config.imgmath_font_size * 1.2)), 'preamble': config.imgmath_latex_preamble, + 'tightpage': '' if image_format == 'png' else ',tightpage', 'math': math } @@ -201,8 +221,18 @@ def convert_dvi_to_svg(dvipath: str, builder: Builder) -> Tuple[str, int]: command.extend(builder.config.imgmath_dvisvgm_args) command.append(dvipath) - convert_dvi_to_image(command, name) - return filename, None + stdout, stderr = convert_dvi_to_image(command, name) + + depth = None + if builder.config.imgmath_use_preview: + for line in stderr.splitlines(): # not stdout ! + matched = depthsvg_re.match(line) + if matched: + depth = round(float(matched.group(1)) * 100 / 72.27) # assume 100ppi + write_svg_depth(filename, depth) + break + + return filename, depth def render_math(self: HTMLTranslator, math: str) -> Tuple[str, int]: @@ -223,13 +253,19 @@ def render_math(self: HTMLTranslator, math: str) -> Tuple[str, int]: if image_format not in SUPPORT_FORMAT: raise MathExtError('imgmath_image_format must be either "png" or "svg"') - latex = generate_latex_macro(math, self.builder.config, self.builder.confdir) + latex = generate_latex_macro(image_format, + math, + self.builder.config, + self.builder.confdir) filename = "%s.%s" % (sha1(latex.encode()).hexdigest(), image_format) relfn = posixpath.join(self.builder.imgpath, 'math', filename) outfn = path.join(self.builder.outdir, self.builder.imagedir, 'math', filename) if path.isfile(outfn): - depth = read_png_depth(outfn) + if image_format == 'png': + depth = read_png_depth(outfn) + elif image_format == 'svg': + depth = read_svg_depth(outfn) return relfn, depth # if latex or dvipng (dvisvgm) has failed once, don't bother to try again diff --git a/sphinx/templates/imgmath/preview.tex_t b/sphinx/templates/imgmath/preview.tex_t index 8dd24c108..f3fdcda07 100644 --- a/sphinx/templates/imgmath/preview.tex_t +++ b/sphinx/templates/imgmath/preview.tex_t @@ -9,7 +9,7 @@ \pagestyle{empty} <%= preamble %> -\usepackage[active]{preview} +\usepackage[active<%= tightpage %>]{preview} \begin{document} \begin{preview} From 505ff622c261128cb3679e5fc7f365041d3a0940 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 24 Apr 2019 11:17:27 +0200 Subject: [PATCH 3/6] More robust code for getting saved "depth" of svg inline math snippet --- doc/usage/extensions/math.rst | 22 +++++++++------------- sphinx/ext/imgmath.py | 7 ++++++- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 1c64c5d17..52d0c54c3 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -95,20 +95,17 @@ built: .. confval:: imgmath_use_preview - ``dvipng`` has the ability to determine the "depth" of the rendered text: for - example, when typesetting a fraction inline, the baseline of surrounding text - should not be flush with the bottom of the image, rather the image should - extend a bit below the baseline. This is what TeX calls "depth". When this - is enabled, the images put into the HTML document will get a - ``vertical-align`` style that correctly aligns the baselines. + ``dvipng`` and ``dvisvgm`` have the ability to collect from LaTeX the + "depth" of the rendered text: an inline image should use this "depth" in a + ``vertical-align`` style to be correctly aligned with surrounding text. - Unfortunately, this only works when the `preview-latex package`_ is - installed (on Ubuntu xenial, it is available as `preview-latex-style`_). - Therefore, the default for this option is ``False``. + This mechanism requires the `LaTeX preview package`_ (available as + ``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this + option is ``False`` but it is strongly recommended to set it to ``True``. - .. versionchanged:: 2.1.0 + .. versionchanged:: 2.1 - This option can also be used with ``imgmath_image_format`` set to ``'svg'``. + This option can be used with the ``'svg'`` :confval:`imgmath_image_format`. .. confval:: imgmath_add_tooltips @@ -222,5 +219,4 @@ package jsMath_. It provides this config value: .. _dvisvgm: https://dvisvgm.de/ .. _MathJax: https://www.mathjax.org/ .. _jsMath: http://www.math.union.edu/~dpvc/jsmath/ -.. _preview-latex package: https://www.gnu.org/software/auctex/preview-latex.html -.. _preview-latex-style: https://packages.ubuntu.com/xenial/preview-latex-style +.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html diff --git a/sphinx/ext/imgmath.py b/sphinx/ext/imgmath.py index 6d007407a..51ebbeff4 100644 --- a/sphinx/ext/imgmath.py +++ b/sphinx/ext/imgmath.py @@ -88,6 +88,7 @@ DOC_BODY_PREVIEW = r''' depth_re = re.compile(br'\[\d+ depth=(-?\d+)\]') depthsvg_re = re.compile(br'.*, depth=(.*)pt') +depthsvgcomment_re = re.compile(r'') def read_svg_depth(filename): @@ -97,7 +98,11 @@ def read_svg_depth(filename): with open(filename, 'r') as f: for line in f: pass - return int(line[11:-4]) + # Only last line is checked + matched = depthsvgcomment_re.match(line) + if matched: + return int(matched.group(1)) + return None def write_svg_depth(filename, depth): From da3763170e7b1211ae4787a92453cf769ce6b614 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 24 Apr 2019 12:03:45 +0200 Subject: [PATCH 4/6] Reorganize documentation of the imgmath configuration variables --- doc/usage/extensions/math.rst | 133 ++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 62 deletions(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 52d0c54c3..75cafff6b 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -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 have both programs available. -There are various config values you can set to influence how the images are -built: +There are various configuration values you can set to influence how the images +are built: .. confval:: imgmath_image_format - The output image format. The default is ``'png'``. It should be either - ``'png'`` or ``'svg'``. - -.. 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 ` - 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'``. + The output image format. The default is ``'png'``. It should be either + ``'png'`` or ``'svg'``. The image is produced by first executing ``latex`` + on the TeX mathematical mark-up then (depending on the requested format) + either `dvipng`_ or `dvisvgm`_. .. confval:: imgmath_use_preview - ``dvipng`` and ``dvisvgm`` have the ability to collect from LaTeX the - "depth" of the rendered text: an inline image should use this "depth" in a - ``vertical-align`` style to be correctly aligned with surrounding text. + ``dvipng`` and ``dvisvgm`` both have the ability to collect from LaTeX the + "depth" of the rendered math: an inline image should use this "depth" in a + ``vertical-align`` style to get correctly aligned with surrounding text. This mechanism requires the `LaTeX preview package`_ (available as ``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 ``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 ` + 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 ------------------------------------------------------- @@ -217,6 +225,7 @@ package jsMath_. It provides this config value: .. _dvipng: https://savannah.nongnu.org/projects/dvipng/ .. _dvisvgm: https://dvisvgm.de/ +.. _dvisvgm FAQ: https://dvisvgm.de/FAQ .. _MathJax: https://www.mathjax.org/ .. _jsMath: http://www.math.union.edu/~dpvc/jsmath/ .. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html From bfe921b3b238721ba3723330483be113ae8e68e3 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 1 Aug 2019 17:39:03 +0200 Subject: [PATCH 5/6] Add Python3 type annotation to cherry-picked #6310 for 2.2.0 release --- sphinx/ext/imgmath.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sphinx/ext/imgmath.py b/sphinx/ext/imgmath.py index 51ebbeff4..b1d33b833 100644 --- a/sphinx/ext/imgmath.py +++ b/sphinx/ext/imgmath.py @@ -91,8 +91,7 @@ depthsvg_re = re.compile(br'.*, depth=(.*)pt') depthsvgcomment_re = re.compile(r'') -def read_svg_depth(filename): - # type: (str) -> int +def read_svg_depth(filename: str) -> int: """Read the depth from comment at last line of SVG file """ with open(filename, 'r') as f: @@ -105,8 +104,7 @@ def read_svg_depth(filename): return None -def write_svg_depth(filename, depth): - # type: (str, int) -> None +def write_svg_depth(filename: str, depth:int) -> None: """Write the depth to SVG file as a comment at end of file """ with open(filename, 'a') as f: From 763908c75a8119f85cbcc07d4135c4ef0a8fbf78 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 1 Aug 2019 17:43:44 +0200 Subject: [PATCH 6/6] Update CHANGES for cherry-picked #6310 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index adeb8ad04..7e0ac0551 100644 --- a/CHANGES +++ b/CHANGES @@ -32,6 +32,8 @@ Features added * #6514: html: Add a label to search input for accessability purposes * #5602: apidoc: Add ``--templatedir`` option * #6475: Add ``override`` argument to ``app.add_autodocumenter()`` +* #6310: imgmath: let :confval:`imgmath_use_preview` work also with the SVG + format for images rendering inline math * #6533: LaTeX: refactor visit_enumerated_list() to use ``\sphinxsetlistlabels`` Bugs fixed