我正在用 Python 编写一些数学代码并使用 Sphinx 来生成文档。我知道 Sphinx 可以处理 Python 文档字符串中的 LaTeX 代码；见https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathbase。如何创建 LaTeX 宏，例如 \newcommand{\cG}{\mathcal{G}}，以在 Python 文档字符串中使用？
【问题讨论】：
标签： python macros latex python-sphinx
如果您使用的是 MathJax，这里有一个可能的解决方案。我仍在寻找更好的解决方案，但如果您需要快速破解，它可能会有所帮助。
在html_static_path 配置选项（通常为_static）中指定的目录下创建一个文件，例如mathconf.js。这将包含 MathJax 的 JS 配置。例如（来自MathJax documentation）：
MathJax.Hub.Config({
TeX: {
Macros: {
RR: '{\\bf R}',
bold: ['{\\bf #1}', 1]
}
}
});
您可以按照上述语法添加更多命令。显示的内容定义了宏 \RR 和 \bold{#1}，最后一个接受一个参数。
在_templates 目录中添加一个layout.html 文件。想法是扩展当前主题，因此它搜索以前的 MathJax 配置文件。因此，内容是：
{% extends "!layout.html" %}
{% set script_files = script_files + ["_static/mathconf.js"] %}
请注意，在这种情况下它是_static 目录，因为在这种情况下它指的是在构建之后 搜索的位置。 Sphinx 会将文件从html_static_path 移动到构建目录下的_static 目录。
【讨论】：
<script type="text/x-mathjax-config"> src="_static/mathconf.js"></script>（请参阅 docs.mathjax.org/en/latest/…）。
啊哈，我找到了一个适用于 Sphinx pngmath 扩展的解决方案。这是 Sage（开源数学软件）使用的技巧；灵感来自http://www.sagemath.org/doc/reference/sage/misc/latex_macros.html。
要将您自己的 Latex 宏添加到 Sphinx 文档：
1) 创建一个文件，例如“latex_macros.sty”，其中包含您的宏（每行一个），然后将其放在与您的 Sphinx conf.py 文件相同的目录中；
2) 将以下代码添加到您的 Sphinx conf.py 文件中：
# Additional stuff for the LaTeX preamble.
latex_elements['preamble'] = '\usepackage{amsmath}\n\usepackage{amssymb}\n'
#####################################################
# add LaTeX macros
f = file('latex_macros.sty')
try:
pngmath_latex_preamble # check whether this is already defined
except NameError:
pngmath_latex_preamble = ""
for macro in f:
# used when building latex and pdf versions
latex_elements['preamble'] += macro + '\n'
# used when building html version
pngmath_latex_preamble += macro + '\n'
#####################################################
【讨论】：
如果您使用的是 pngmath 扩展，则可以通过将其插入到 conf.py 脚本中来将其放在序言中：
pngmath_latex_preamble = r"\newcommand{\cG}{\mathcal{G}}"
【讨论】：
要添加到 @Keta 自 2018 年 8 月以来的回答和此提交 (https://github.com/sphinx-doc/sphinx/pull/5230/files)，您可以根据文档 (http://www.sphinx-doc.org/en/master/usage/extensions/math.html?#confval-mathjax_config) 在 conf.py 中使用 mathjax_config
因此例如可以添加以下内容，
mathjax_config = {
"TeX": {
"Macros": {
"RR": '{\\bf R}',
"bold": ['{\\bf #1}',1]
}
}
}
【讨论】：
在 sphinx-doc 2.4.3 上测试的建议解决方案（例如，sphinx-quickstart --version）
Sphinx-doc 允许通过 mathjax_config 对 MathJax 进行额外的调整。最终目标是我们要在conf.py 中实现以下内容：
mathjax_config = {
'TeX': {
'Macros': {
# Math notation
"Z": "\\mathbb{Z}", # set of integers
# MoA notations
"minus": "{}^{\\boldsymbol{\\mbox{-}}\\!}", # scalar negation operator
}
}
}
我们可以像上面那样手动完成。但是，我们可以通过解析包含所有宏命令的单独 .tex 文件自动填充 mathjax_config 来做得更好。
例如，我有 mathsymbols.tex 与 conf.py 位于同一级别，内容如下所示：
\DeclareRobustCommand{\ojoin}{\rule[-0.12ex]{.3em}{.4pt}\llap{\rule[1.2ex]{.3em}{.4pt}}}
\newcommand{\leftouterjoin}{\mathrel{\ojoin\mkern-6.5mu\Join}}
\newcommand{\rightouterjoin}{\mathrel{\Join\mkern-6.5mu\ojoin}}
\newcommand{\fullouterjoin}{\mathrel{\ojoin\mkern-6.5mu\Join\mkern-6.5mu\ojoin}}
那么，在conf.py里面，我们可以写：
mathjax_config = { 'TeX': {'Macros': {}}}
with open('mathsymbols.tex', 'r') as f:
for line in f:
macros = re.findall(r'\\(DeclareRobustCommand|newcommand){\\(.*?)}(\[(\d)\])?{(.+)}', line)
for macro in macros:
if len(macro[2]) == 0:
mathjax_config['TeX']['Macros'][macro[1]] = "{"+macro[4]+"}"
else:
mathjax_config['TeX']['Macros'][macro[1]] = ["{"+macro[4]+"}", int(macro[3])]
自动填充mathjax_config，我们就完成了。
通过上面的例子，我们可以在 sphinx-doc 中使用\leftouterjoin LaTeX 宏。
【讨论】：