在记录交互式会话时如何更改 Sphinx 显示的提示？

Posted 2023-03-30

【中文标题】在记录交互式会话时如何更改 Sphinx 显示的提示？

【英文标题】：How can I change the prompt displayed by Sphinx when documenting interactive sessions?

【发布时间】：2012-05-09 17:56:53

【问题描述】：

我目前正在使用Sphinx 记录一个混合语言项目，因此该文档不仅包含 Python 中的交互式会话示例，还包含 bash 和 Windows 命令行以及 MATLAB 和其他解释器中的交互式会话示例.虽然 Pygments 可以很好地突出显示所有内容，但到目前为止，我在文档中包含的所有交互式会话都显示在 html 输出中，前面有 Python 提示符>>>。例如，在记录 bash 会话时，如何将该提示更改为 $？

---

编辑澄清：

如 Sphinx 手册中所述，在“Showing code examples”下，Sphinx 文档的 ReST 源可以包含如下代码：

>>> # python code here
>>> print "foo"
foo

然后，此代码将转换为 Python 标准库文档中 the documentation of argparse 中演示的标记，将 >>> 之后的代码显示为突出显示的 sn-p。虽然很明显可以简单地用其他提示字符排版未突出显示的块，但我想知道如何将>>> 以外的提示与the argparse example 中显示的交互式提示样式结合起来。

【问题讨论】：

我不确定我是否遵循。 Sphinx 不会在 HTML 输出中添加提示；提示应该在文档源中。您能否向我们展示一个示例交互式 bash 会话的 reST 源代码？

如果我向 ReST 源添加一些看起来像 bash 会话的传统文本表示的东西，每行以 $ 开头，那么 Sphinx 将不会以代码样式排版。另一方面，如果我用>>> 开始一个ReST 源代码行，那么它会这样做，遵守最新的.. highlight:: 指令。也就是说，HTML 输出仍然包含>>>，没有明显的方式来改变提示的排版。

【参考方案1】：

您可以使用 $ 作为 bash sn-ps 的提示符，但如果您想很好地突出显示输出，则不能将其用于 Python。

>>> 被识别为交互式 Python 提示符。但是使用另一个提示是行不通的。 The documentation 说：“普通 Python 代码只有在可解析时才会突出显示”，类似于

$ import sys 

或

>> import sys 

不能像 Python 一样解析。

可以使用扩展使 Sphinx 接受其他 Python 提示。 ipython directive 是一个例子（未经我测试）。

---

这些例子很适合我：

.. code-block:: bash

   $ pwd
   /home
   $ echo TEST
   TEST

.. code-block:: python

   >>> import sys
   >>> print "X"
   X

以下产生相同的格式和突出显示：

.. highlight:: bash

::

   $ pwd
   /home
   $ echo TEST
   TEST

.. highlight:: python

::

   >>> import sys
   >>> print "X"
   X

对于 Python 交互式会话，实际上不需要额外的标记（除非最新的 .. highlight:: 指令的目标不是 python）。 Sphinx 自动识别>>>：

>>> import sys
>>> print "X"
X

在没有任何提示的情况下，代码必须在代码块（或文字块）中才能正确格式化：

.. code-block:: python

   import sys
   print "X"