时间戳

首页 > 解决方案 > 如何将代码片段添加到 python docstring（不是 doctest）？

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

问题描述

我想提供代码片段来展示如何在 python 中使用特定的方法或类。我怎样才能做到这一点？

在 Java中可以使用<pre> ... </pre>这样做。

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

标签： pythoncode-snippetsdocstringdoctestcode-documentation

解决方案

DocStrings 不是唯一的方法。如果您使用 Sphinx 生成文档，那么您应该阅读这个。

例子

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
        """

推荐阅读