latex - hf-tikz 和 sphinx 玩得不好

Question

我正在尝试在 sphinx 中为我的矩阵添加一些颜色。我之前使用的是hf-tikz。但是，当我将它添加到 Sphinx 时，它会错误地呈现它。

我试图得到的结果是

我得到的结果是

这是我拥有的代码。

main.rst：

.. math::

    \left(\begin{array}{cc}
        \tikzmarkin[style red]{a}a\tikzmarkend{a}
      & \tikzmarkin[style green]{b}b\tikzmarkend{b} \\
        \tikzmarkin[style blue]{c}c\tikzmarkend{c}
      & \tikzmarkin[style orange]{d}d\tikzmarkend{d} \\
    \end{array}\right)
    \star
    \left(\begin{array}{cc}
        \tikzmarkin[style red]{w}w\tikzmarkend{w}
      & \tikzmarkin[style green]{x}x\tikzmarkend{x} \\
        \tikzmarkin[style blue]{y}y\tikzmarkend{y}
      & \tikzmarkin[style orange]{z}z\tikzmarkend{z} \\
    \end{array}\right)
    =
    \left(\begin{array}{cc}
        \tikzmarkin[hor=style red]{aw}{a\star w}\tikzmarkend{aw}
      & \tikzmarkin[hor=style green]{bx}b\star x\tikzmarkend{bx} \\
        \tikzmarkin[hor=style blue]{cy}c\star y\tikzmarkend{cy}
      & \tikzmarkin[hor=style orange]{dz}d\star z\tikzmarkend{dz} \\
    \end{array}\right)

配置文件

extensions = [
  'sphinx.ext.imgmath',
]

# Math configurations (https://tex.stackexchange.com/a/69770/51173)
imgmath_image_format = 'svg'
imgmath_use_preview = True
imgmath_latex_preamble = r'''
  \usepackage{xcolor}
  \usepackage[customcolors]{hf-tikz}
  \colorlet{myred}{red!50!purple!30}
  \colorlet{mygreen}{green!50!lime!60}
  \colorlet{myblue}{blue!50!white!50}
  \colorlet{myorange}{orange!80!red!60}
  \colorlet{mycyan}{cyan!90!blue!60}
  \colorlet{mymagenta}{magenta!90!red!60}
  \tikzset{
    style red/.style={
      set fill color=myred,
      set border color=white,
    },
    style green/.style={
      set fill color=mygreen,
      set border color=white,
    },
    style blue/.style={
      set fill color=myblue,
      set border color=white,
    },
    style orange/.style={
      set fill color=myorange,
      set border color=white,
    },
    style cyan/.style={
      set fill color=mycyan,
      set border color=white,
    },
    style magenta/.style={
      set fill color=mymagenta,
      set border color=white,
    },
    %
    hor/.style={
      above left offset={-0.15,0.31},
      below right offset={0.15,-0.125},
      #1
    },
    ver/.style={
      above left offset={-0.1,0.3},
      below right offset={0.15,-0.15},
      #1
    }
  }
'''

生成文件

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

制作.bat

@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
    set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

if "%1" == "" goto help

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
    echo.
    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
    echo.installed, then set the SPHINXBUILD environment variable to point
    echo.to the full path of the 'sphinx-build' executable. Alternatively you
    echo.may add the Sphinx directory to PATH.
    echo.
    echo.If you don't have Sphinx installed, grab it from
    echo.http://sphinx-doc.org/
    exit /b 1
)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd

编辑：添加了用于构建 rst 的 makefile

标签： latexpython-sphinxtikz

Answer 1

I think I found why this was happening: the problem was in the sphinx.ext.imgmath extension + hf-tikz not working well with the DVI files.

When converting the math equations, sphinx creates a very basic latex document, and compiles it using latexpdf into a DVI file. After that the file is converted into an SVG, and the resulting svg file is copied to the sphinx's _build directory. The problem is that dvisvgm (used by imgmath) cannot convert tikz stuff. Alternative would be using extended DVI, but that doesn't work well either.

The solution is to compile everything into PDF, and convert that pdf into SVG. This is slightly problematic, and the only way I found is to use pdf2svg + pdfcrop. I ended up modifying the imgmath.py into a custom extension. Below are the changes that I put in the imgmath.py. The changes require the use of external applications, so I don't think there is a merit in creating a pull request (at least not with a more scalable solution).

Changes in the imgmath.py:

1. Create a new method:

def convert_pdf_to_svg(pdfpath, builder):
    # type: (str, Builder) -> Tuple[str, int]
    """Convert DVI file to SVG image."""
    tempdir = ensure_tempdir(builder)
    filename = path.join(tempdir, 'math.svg')

    name = 'pdfcrop'
    command = [name, pdfpath, pdfpath]
    run_external_command(command, name)

    name = 'pdf2svg'
    command = [name, pdfpath, filename]
    run_external_command(command, name)
    return filename, None

2. In the compile_math function, inside the try block, replace the return statement with the following

if builder.config.imgmath_pdf2svg:
  return path.join(tempdir, 'math.pdf')
else:
  return path.join(tempdir, 'math.dvi')

3. Inside the render_math method, in the block titles # .dvi -> .png/svg, replace the try block with the following

try:
    if image_format == 'png':
        imgpath, depth = convert_dvi_to_png(dvipath, self.builder)
    elif image_format == 'svg':
        if self.builder.config.imgmath_pdf2svg:
            imgpath, depth = convert_pdf_to_svg(dvipath, self.builder)
        else:
            imgpath, depth = convert_dvi_to_svg(dvipath, self.builder)
except InvokeError:
    self.builder._imgmath_warned_image_translator = True  # type: ignore
    return None, None

4. Finally, add a new configuration entry in the very end of the imgmath.py:

    app.add_config_value('imgmath_pdf2svg', False, 'html')

After that, you can write in the conf.py to enable the tikz images.

imgmath_image_format = 'svg'
imgmath_latex = 'latexmk'
imgmath_latex_args = ['-pdf']
imgmath_pdf2svg = True  # Available only in the custom `imgmath.py`

patch for imgmath extension. Includes some other stuff :)

The patch goes a->b.

--- a/imgmath.py
+++ b/imgmath.py
@@ -15,7 +15,7 @@
 import sys
 import tempfile
 from hashlib import sha1
-from os import path
+from os import path, symlink
 from subprocess import CalledProcessError, PIPE
 from typing import Any, Dict, List, Tuple

@@ -157,6 +157,11 @@
     with open(filename, 'w', encoding='utf-8') as f:
         f.write(latex)

+    for add_file in builder.config.imgmath_latex_additional_files:
+        filename = path.join(tempdir, path.basename(add_file))
+        if not path.exists(filename):
+            symlink(path.join(builder.confdir, add_file), filename)
+
     # build latex command; old versions of latex don't have the
     # --output-directory option, so we have to manually chdir to the
     # temp dir to run it.
@@ -165,9 +170,15 @@
     command.extend(builder.config.imgmath_latex_args)
     command.append('math.tex')

+    output_extension = 'dvi'
+    if builder.config.imgmath_latex == 'xelatex':
+        output_extension = 'xdv'
+    if builder.config.imgmath_pdf2svg:
+        output_extension = 'pdf'
+
     try:
         subprocess.run(command, stdout=PIPE, stderr=PIPE, cwd=tempdir, check=True)
-        return path.join(tempdir, 'math.dvi')
+        return path.join(tempdir, 'math.' + output_extension)
     except OSError:
         logger.warning(__('LaTeX command %r cannot be run (needed for math '
                           'display), check the imgmath_latex setting'),
@@ -177,7 +188,7 @@
         raise MathExtError('latex exited with error', exc.stderr, exc.stdout)


-def convert_dvi_to_image(command: List[str], name: str) -> Tuple[bytes, bytes]:
+def run_external_command(command: List[str], name: str) -> Tuple[bytes, bytes]:
     """Convert DVI file to specific image format."""
     try:
         ret = subprocess.run(command, stdout=PIPE, stderr=PIPE, check=True)
@@ -203,7 +214,7 @@
         command.append('--depth')
     command.append(dvipath)

-    stdout, stderr = convert_dvi_to_image(command, name)
+    stdout, stderr = run_external_command(command, name)

     depth = None
     if builder.config.imgmath_use_preview:
@@ -227,7 +238,7 @@
     command.extend(builder.config.imgmath_dvisvgm_args)
     command.append(dvipath)

-    stdout, stderr = convert_dvi_to_image(command, name)
+    stdout, stderr = run_external_command(command, name)

     depth = None
     if builder.config.imgmath_use_preview:
@@ -239,6 +250,21 @@
                 break

     return filename, depth
+
+def convert_pdf_to_svg(pdfpath, builder):
+    # type: (str, Builder) -> Tuple[str, int]
+    """Convert DVI file to SVG image."""
+    tempdir = ensure_tempdir(builder)
+    filename = path.join(tempdir, 'math.svg')
+
+    name = 'pdfcrop'
+    command = [name, pdfpath, pdfpath]
+    run_external_command(command, name)
+
+    name = 'pdf2svg'
+    command = [name, pdfpath, filename]
+    run_external_command(command, name)
+    return filename, None


 def render_math(self: HTMLTranslator, math: str) -> Tuple[str, int]:
@@ -291,7 +317,10 @@
         if image_format == 'png':
             imgpath, depth = convert_dvi_to_png(dvipath, self.builder)
         elif image_format == 'svg':
-            imgpath, depth = convert_dvi_to_svg(dvipath, self.builder)
+            if self.builder.config.imgmath_pdf2svg:
+                imgpath, depth = convert_pdf_to_svg(dvipath, self.builder)
+            else:
+                imgpath, depth = convert_dvi_to_svg(dvipath, self.builder)
     except InvokeError:
         self.builder._imgmath_warned_image_translator = True  # type: ignore
         return None, None
@@ -396,8 +425,10 @@
                          ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'],
                          'html')
     app.add_config_value('imgmath_dvisvgm_args', ['--no-fonts'], 'html')
+    app.add_config_value('imgmath_pdf2svg', False, 'html')
     app.add_config_value('imgmath_latex_args', [], 'html')
     app.add_config_value('imgmath_latex_preamble', '', 'html')
+    app.add_config_value('imgmath_latex_additional_files', [], 'html')
     app.add_config_value('imgmath_add_tooltips', True, 'html')
     app.add_config_value('imgmath_font_size', 12, 'html')
     app.connect('build-finished', cleanup_tempdir)