如何在code-block指令中插入:math:等role角色并正确渲染？

如果直接在code-block中插入:math:角色，Sphinx会将其视为纯文本，无法正确渲染数学公式。以下两种方法可以解决这个问题：

方法1：使用parsed-literal块 #

parsed-literal块会解析其中的inline角色（包括:math:），同时保留代码的排版格式。示例：

.. parsed-literal::

:math:2^{64} - 1

这种方式适合不需要语法高亮的代码场景，能直接渲染数学公式。

方法2：给code-block添加escape选项 #

如果需要保留语法高亮功能，可以给code-block添加:escape:参数，并用反斜杠转义角色标记，让Sphinx识别并渲染math角色：

.. code-block:: text :escape:

:math:2^{64} - 1

这里的text可以替换为你需要的编程语言（比如python），:escape:参数允许块内的转义字符被解析，从而触发math角色的渲染逻辑。

内容的提问来源于stack exchange，提问作者Ольга Зайчук