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

Question

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

我现在想将这些示例脚本也包含在我的文档中，以便我可以将它们作为教程重用，并且在对代码应用更改时不必同时更改示例和教程，但可以直接拥有这两个内容在一起并始终保持最新状态。

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

你们中有人知道这是如何实现的吗？

非常感谢您的帮助！

Answer 1

您可以使用viewcode sphinx 扩展来达到您的目的。

例如：

假设你有一个模块 -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

因此，您甚至可以在教程中添加指向此页面的明确链接。

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