在 Sphinx 中创建 LaTeX 数学宏

Question

我正在用 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 文档字符串中使用？

Answer 1

如果您使用 MathJax，这里有一个可能的解决方案。我仍在寻找更好的解决方案，但如果您需要快速破解，它可能会有所帮助。

1. 在

   html_static_path

   配置选项（通常为

   _static

   ）中指定的目录下创建一个文件，例如

   mathconf.js

   。这将包含 MathJax 的 JS 配置。例如（来自 MathJax 文档）：

   MathJax.Hub.Config({
     TeX: {
       Macros: {
         RR: '{\\bf R}',
         bold: ['{\\bf #1}', 1]
       }
     }
   });
   

   您可以按照上面的语法添加更多命令。显示的内容定义了宏

   \RR

   和

   \bold{#1}

   ，最后一个接受一个参数。

2. 在

   layout.html

   目录下添加

   _templates

   文件。这个想法是扩展当前主题，因此它搜索以前的 MathJax 配置文件。因此，内容是：

   {% extends "!layout.html" %}
   {% set script_files = script_files + ["_static/mathconf.js"] %}
   

   请注意，在这种情况下，它是

   _static

   目录，因为在这种情况下，它指的是在构建之后之后搜索的位置。 Sphinx 会将文件从 html_static_path

    移动到构建目录下的 

   _static

    目录。

Answer 2

啊哈，我找到了一个与 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'

#####################################################

Answer 3

要添加@Keta自2018年8月以来的答案和此提交（

https://github.com/sphinx-doc/sphinx/pull/5230/files），您可以根据以下内容在conf.py中使用mathjax_config

文档 (

http://www.sphinx-doc.org/en/master/usage/extensions/math.html?#confval-mathjax_config)

例如可以添加以下内容，

mathjax_config = {                  
    "TeX": {                        
        "Macros": {                 
            "RR": '{\\bf R}',       
            "bold": ['{\\bf #1}',1] 
            }                       
        }                           
    }                               

Answer 4

如果您使用 pngmath 扩展，您可以通过将其插入到 conf.py 脚本中来将其放在序言中：

pngmath_latex_preamble = r"\newcommand{\cG}{\mathcal{G}}"

Answer 5

建议的解决方案在 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
        }
   }
}

我们可以像上面那样手动执行此操作。但是，我们可以通过解析包含所有宏命令的单独

mathjax_config

 文件自动填充 

.tex

 来做得更好。

例如，我有

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 宏。 

Answer 6

如果 HTML+MathJax 是唯一的输出格式，则以下内容可以在普通 Docutils 中开箱即用：

.. math:: \newcommand{\half}{\frac{1}{2}}
          0.5 = \half

With MathJax, we can use the macro later: :math:`\half+\half=1`.

使用 LaTeX，

\newcommand

 定义对于第一个方程而言是局部的。