Question

我正在用Python编写一些数学代码，并使用Sphinx生成文档。我知道Sphinx可以在Python文档字符串中处理LaTeX代码;见http://sphinx.pocoo.org/latest/ext/math.html#module-sphinx.ext.mathbase。如何创建LaTeX宏（例如\newcommand{\cG}{\mathcal{G}}）以在Python文档字符串中使用？

Answer 1

如果您使用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}，最后一个接受一个参数。
在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

如果您正在使用pngmath扩展程序，可以将其插入前导码中，方法是将其插入到conf.py脚本中：

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

Answer 4

要添加自@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] 
            }                       
        }                           
    }

Answer 5

建议的解决方案已在sphinx-doc 2.4.3（例如0.2）上进行了测试

Sphinx-doc允许通过mathjax_config对MathJax进行其他调整。最终目标是我们要在sphinx-quickstart --version中实现以下目标：

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])]，我们就完成了。

在上面的示例中，我们可以在sphinx-doc中使用mathjax_config LaTeX宏。

在Sphinx中创建LaTeX数学宏

5 个答案: