如何在RST标记中定义可用于文本和公式的数学符号？

针对Read the Docs环境，有几种实用方案能实现一次定义、全文档复用数学符号，兼顾文本和数学块的使用需求：

方案一：基础替换+LaTeX/MathJax预定义（推荐） #

这种方式分别处理文本和数学块的复用，配置简单易维护：

1. 文本中的复用：用RST的替换定义，可放在文档开头或全局配置中

   # 单个文档内定义，放在文档最顶部
   .. |x1| replace:: :math:`x_1`
   .. |x2| replace:: :math:`x_2`
   
   # 文本中直接引用
   The ratio of the two variables |x1| and |x2| is given by the following formula:
   

2. 数学块中的复用：根据渲染环境配置预定义命令
   • 若生成PDF（LaTeX渲染）：在项目的conf.py中添加LaTeX预定义

     latex_elements = {
         'preamble': r'\newcommand{\x1}{x_1} \newcommand{\x2}{x_2}'
     }
     

   • 若网页版（MathJax渲染）：在conf.py的rst_prolog中添加MathJax配置

     rst_prolog = """
     .. raw:: html
     
         <script type="text/x-mathjax-config">
             MathJax.Hub.Config({
                 TeX: {
                     Macros: {
                         x1: "{x_1}",
                         x2: "{x_2}"
                     }
                 }
             });
         </script>
     """
     

   • 数学块中直接引用预定义的命令：

     .. math::
             r = \frac{|\x1|}{|\x2|}
     

方案二：全局统一配置（多文档项目适用） #

如果是多文档项目，可把替换和预定义都放在conf.py的rst_prolog中，实现全项目自动加载：

rst_prolog = """
# 文本替换定义
.. |x1| replace:: :math:`x_1`
.. |x2| replace:: :math:`x_2`

# MathJax预定义（网页渲染用）
.. raw:: html

    <script type="text/x-mathjax-config">
        MathJax.Hub.Config({
            TeX: {
                Macros: {
                    x1: "{x_1}",
                    x2: "{x_2}"
                }
            }
        });
    </script>
"""

# LaTeX预定义（PDF渲染用）
latex_elements = {
    'preamble': r'\newcommand{\x1}{x_1} \newcommand{\x2}{x_2}'
}

之后所有文档的文本里直接用|x1|，数学块里直接用\x1即可。

注意事项 #

• 替换定义的优先级：文档内的替换会覆盖全局rst_prolog中的定义，方便局部调整
• MathJax的配置需要放在raw:: html块中，确保能被网页渲染引擎识别
• 如果只需要网页版渲染，可省略LaTeX预定义的配置

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