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

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]的链接，如下所示：

<< img src =“ https://image.soinside.com/eyJ1cmwiOiAiaHR0cHM6Ly9pLnN0YWNrLmltZ3VyLmNvbS9DZ2VjNS5wbmcifQ==” alt =“在此处输入图像描述”>

单击[source]，将带您到源代码的html。 Sphinx本质上在以下目录中生成代码的HTML

_build/html/_modules/BeautifulSoup.html

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

这唯一不会做的是将文档字符串分成常规文本，将代码分成代码块。但这可以解决您不必每次都更新教程和代码的问题。