在Sphinx生成的文档中包含一个带有注释的Python脚本

2024-03-29 09:56:42 发布

您现在位置:Python中文网/ 问答频道 /正文

我在一个Python项目中工作,我使用Sphinx生成其html在线文档。该项目还包含几个Python脚本,展示了如何使用包含的工具的示例,而所有这些文件都被广泛地注释以解释它的工作原理。在

我现在也希望在我的文档中包括这些示例脚本,这样我就可以将它们作为教程重用,并且在对代码应用更改时,不必同时更改示例和教程,而是可以将这两个内容直接放在一起并始终保持最新。在

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

你们有人知道这是怎么做到的吗?在

非常感谢你的帮助!在


Tags: 文件工具项目代码文档文本脚本示例
1条回答
网友
1楼 · 发布于 2024-03-29 09:56:42

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

例如:

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

然后创建一个包含以下内容的文件BeautifulSoup.rst(为模块生成文档)

.. automodule:: BeautifulSoup
    :members:

一旦您在conf.py中启用了此扩展,并构建了html:

^{pr2}$

您将在类和成员旁边看到一个名为[source]的链接,如下所示:

enter image description here

单击[source]可进入源代码的html。实际上,Sphinx在目录中生成以下HTML

_build/html/_modules/BeautifulSoup.html

因此,您甚至可以在教程中添加指向此页面的显式链接。在

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

相关问题 更多 >