如何解决Sphinx生成含西里尔字符LaTeX公式的Confluence文档时的ASCII解码错误？

问题场景 #

尝试用Sphinx从包含西里尔字符LaTeX公式的RST文档生成Confluence文档，配置文件conf.py如下：

extensions = [
    'sphinxcontrib.confluencebuilder',
]

confluence_publish = True
confluence_space_key = 'user_space'
confluence_server_url = 'https://confluence.com'
confluence_page_hierarchy = True
confluence_page_generation_notice = True
confluence_prev_next_buttons_location = 'top'

confluence_server_user = 'login'
confluence_server_pass = 'password'
source_encoding = 'utf-8'

平台：Linux (Linux-5.15.153.1-microsoft-standard-WSL2-x86_64-with-glibc2.29)
扩展版本：

• sphinx.ext.mathjax (7.1.2)
• alabaster (0.7.13)
• sphinxcontrib.applehelp (1.0.4)
• sphinxcontrib.devhelp (1.0.2)
• sphinxcontrib.htmlhelp (2.0.1)
• sphinxcontrib.serializinghtml (1.1.5)
• sphinxcontrib.qthelp (1.0.3)
• sphinxcontrib.confluencebuilder (2.5.2)

执行构建命令：

sphinx-build -b confluence path/to/rst tmp/path

出现如下回溯错误：

Traceback (most recent call last):
    File "/usr/local/lib/python3.8/dist-packages/sphinx/cmd/build.py", line 290, in build_main
    app.build(args.force_all, args.filenames)
    File "/usr/local/lib/python3.8/dist-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
    File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(to_build,
    File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
    File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 556, in write
    self.prepare_writing(docnames)
    File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/builder.py", line 317, in prepare_writing
    self._prepare_doctree_writing(docname, doctree)
    File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/builder.py", line 399, in _prepare_doctree_writing
    doctree_transmute(self, doctree)
    File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/transmute/__init__.py", line 90, in doctree_transmute
    prepare_math_images(builder, doctree)
    File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/transmute/__init__.py", line 132, in prepare_math_images
    mf, depth = imgmath.render_math(mock_translator, node.astext())
    File "/usr/local/lib/python3.8/dist-packages/sphinx/ext/imgmath.py", line 259, in render_math
    dvipath = compile_math(latex, self.builder)
    File "/usr/local/lib/python3.8/dist-packages/sphinx/ext/imgmath.py", line 143, in compile_math
    subprocess.run(command, capture_output=True, cwd=tempdir, check=True,
    File "/usr/lib/python3.8/subprocess.py", line 495, in run
    stdout, stderr = process.communicate(input, timeout=timeout)
    File "/usr/lib/python3.8/subprocess.py", line 1028, in communicate
    stdout, stderr = self._communicate(input, endtime, timeout)
    File "/usr/lib/python3.8/subprocess.py", line 1906, in _communicate
    stdout = self._translate_newlines(stdout,
    File "/usr/lib/python3.8/subprocess.py", line 905, in _translate_newlines
    data = data.decode(encoding, errors)
UnicodeDecodeError: 'ascii' codec can't decode byte 0xd0 in position 1403: ordinal not in range(128)

错误原因 #

错误出现在subprocess解码LaTeX编译输出时，系统默认编码为ASCII，无法处理包含西里尔字符的输出内容（比如LaTeX编译日志中的非ASCII字符）。

解决方案 #

1. 强制系统环境使用UTF-8编码 #

在执行sphinx-build命令前，设置环境变量：

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

或者将上述环境变量添加到你的shell配置文件（如~/.bashrc或~/.zshrc）中，确保永久生效。

2. 配置Sphinx的imgmath扩展支持UTF-8 #

在conf.py中添加以下配置，确保LaTeX编译时能正确处理西里尔字符：

# 配置LaTeX预amble支持UTF-8
imgmath_latex_preamble = r'\usepackage[utf8]{inputenc}'
# 指定使用支持UTF-8的LaTeX引擎
imgmath_latex_engine = 'pdflatex'

3. 升级相关扩展（可选） #

旧版本的sphinxcontrib.confluencebuilder或Sphinx可能存在编码处理缺陷，升级到最新版本可以避免部分问题：

pip install --upgrade sphinxcontrib-confluencebuilder sphinx

内容的提问来源于stack exchange，提问作者roman