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

【问题标题】：How to add code snippets to python docstring (not as doctest)?如何将代码片段添加到 python docstring（不是 doctest）？
【发布时间】：2019-07-04 18:05:03
【问题描述】：

我想提供代码 sn-ps 来展示如何在 python 中使用特定的方法或类。我该怎么做？

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

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

【问题讨论】：

标签： python code-snippets docstring doctest code-documentation

【解决方案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
        """

【讨论】：

这很好。但如果可能的话，我更愿意阻止文档依赖于另一个包。
刚刚注意到:: 无需安装任何软件包即可工作。所以，我会接受你的回答。