在Sphinx生成的文档中包含注释的Python脚本

Question

我在使用Sphinx生成的html-online-documentation的Python项目上工作。该项目还包含几个Python脚本，其中显示了有关如何使用所包含工具的示例，而所有这些文件都经过广泛评论，以解释其发生的情况。

我现在想在我的文档中包含这些示例脚本，以便我可以将它们作为教程重用，并且在我对代码应用更改时不必更改示例和教程，但可以这两件事直接在一起并且始终是最新的。

我想Sphinx会从上到下解析脚本，并从中生成一个html文件，而注释在页面上显示为文本，代码在代码块中显示。

你们中有谁知道如何实现这一目标吗？

非常感谢你的帮助！

Answer 1

您可以使用viewcode sphinx扩展程序。 http://sphinx-doc.org/latest/ext/viewcode.html

例如：

假设你有一个模块 - BeautifulSoup.py

并使用以下内容创建文件BeautifulSoup.rst（以生成模块的文档）

.. automodule:: BeautifulSoup
    :members:

在conf.py中启用此扩展程序，如下所示，并构建html：

extensions = ['sphinx.ext.autodoc', 
    'sphinx.ext.pngmath',
    'sphinx.ext.viewcode',
    ]

您会看到类和成员旁边有一个名为[source]的链接，如下所示：

点击[source]会转到你的来源的html。 Sphinx基本上在以下目录中生成代码的HTML

_build/html/_modules/BeautifulSoup.html

因此，您甚至可以在教程中为此页面添加显式链接。

唯一不做的是将doc字符串拆分为常规文本和代码块。但它应该解决您不必每次都更新教程和代码的问题。