如何将代码示例嵌入到文档字符串中？

Question

如何将代码嵌入到文档字符串中，以告诉 Sphinx 将代码格式化为与 Markdown 中类似的格式（不同的背景颜色、等宽无衬线字体）？例如记录代码使用示例。

""" This is a module documentation

Use this module like this:

   res = aFunction(something, goes, in)
   print(res.avalue)

"""

Answer 1

有几种方法可以做到这一点。我认为在你的情况下最明智的是

.. code-block::

""" This is a module documentation

Use this module like this:

.. code-block:: python

   res = aFunction(something, goes, in)
   print(res.avalue)

"""

注意指令和代码块之间的空行 - 它必须存在才能使块正确渲染。

Answer 2

另一种突出显示代码的方法（参见 mzjn 在这篇文章中的评论）是在代码之前的行以两个（！）冒号结尾：

""" This is a module documentation

Use this module like this::

   res = aFunction(something, goes, in)
   print(res.avalue)

"""

::

就可以了。