我在一个Python项目中工作,我使用Sphinx生成其html在线文档。该项目还包含几个Python脚本,展示了如何使用包含的工具的示例,而所有这些文件都被广泛地注释以解释它的工作原理。在
我现在也希望在我的文档中包括这些示例脚本,这样我就可以将它们作为教程重用,并且在对代码应用更改时,不必同时更改示例和教程,而是可以将这两个内容直接放在一起并始终保持最新。在
我设想Sphinx从上到下解析脚本,并从中生成一个html文件,而注释在页面上显示为文本,代码在代码块中描述。在
你们有人知道这是怎么做到的吗?在
非常感谢你的帮助!在
Tags:
您可以使用viewcodesphinx扩展。 http://sphinx-doc.org/latest/ext/viewcode.html
例如:
假设您有一个模块-
BeautifulSoup.py
然后创建一个包含以下内容的文件
BeautifulSoup.rst
(为模块生成文档)一旦您在
^{pr2}$conf.py
中启用了此扩展,并构建了html:您将在类和成员旁边看到一个名为
[source]
的链接,如下所示:单击
[source]
可进入源代码的html。实际上,Sphinx在目录中生成以下HTML因此,您甚至可以在教程中添加指向此页面的显式链接。在
唯一不能做的事情是将doc字符串拆分为常规文本,并将代码拆分为代码块。但是它应该解决您不必每次都更新教程和代码的问题。在
相关问题 更多 >
编程相关推荐