如何将代码片段添加到 python docstring（而不是 doctest）？

Question

我想提供代码片段来展示如何使用特定方法或class in python。我该怎么做？

在Java中可以使用<pre> ... </pre>来做到这一点。

Doctest是唯一的方法吗？ 当我查看典型包的现有文档字符串（例如，pandas、numpy 等）时，除了 doctest 之外，我从未看到任何其他内容，它旨在测试该方法，而不仅仅是将文本格式化为 python代码。因此，如果 doctest 是唯一的方法，那么将一段代码格式化为看起来像交互式 python 会话的正确方法是什么？我不想每次都在交互式会话中编写我的代码，然后在我的文档字符串中 c+p。好像不太对。

Answer 1

DocStrings 不是唯一的方法。如果您使用 Sphinx 生成文档，那么您 should read this.

示例

Here is something I want to talk about:: <-- Special syntax to mark code beginning

    def my_fn(foo, bar=True): # Code itself
        """A really useful function.

        Returns None
        """