我最近尝试使用来自Sphinx的sphinx-apidoc来帮助从Python项目的API生成Sphinx特定的restructedText。在
然而,我得到的结果是:
有人知道我是否可以自定义sphinx-api
用于其输出的模板吗?具体来说,我想:
__init__.py
文件中docstring的结果直接显示在包的下面,这样如果我单击一个包名,我看到的第一件事就是包文档。目前,这个文档被放在每个包部分末尾有点奇怪的“模块内容”标题下。在“子模块”和“子包”标题是多余的,因为包/模块的正常标题是“xxx.yyy年包装“和”xxx.yyy.zzz公司模块”。在
我希望上面这个小例子的结构是
在点击包的地方,我在页面上看到的第一件事就是包文档。在
或者甚至只是
是否有某种方法可以从视觉上区分包装/模块(颜色?会徽?)而不是冗长的“包”和“模块”。在
我实现了better-apidoc,这是
sphinx-apidoc
脚本的修补版本,添加了对模板的完全支持。在它添加了一个
-t/ template
选项,允许传递一个模板目录 必须包含模板文件package.rst
和module.rst
。 看到了吗 package.rst 和 module.rst 举个例子。例如。 http://qnet.readthedocs.io/en/latest/API/qnet.algebra.operator_algebra.html。在FWIW,这里有一个完整的脚本,让你做你想要的改变,这也是我想要的改变,在一个“文件名.rst.new“每个文件旁边”文件名.rst“:
sphinxapidoc脚本使用apidoc.py模块。我无法提供详细的说明,但为了删除标题或以其他方式自定义输出,您必须编写本模块的您自己的版本。没有其他的“模板”。在
注意,如果API和模块结构稳定,就不需要重复运行sphinxapidoc。您可以将生成的rst文件后处理一次,然后将它们置于版本控制之下。另请参见https://stackoverflow.com/a/28481785/407651。在
更新
从sphinx2.2.0开始,sphinxapidoc支持模板。见https://stackoverflow.com/a/57520238/407651。在
相关问题 更多 >
编程相关推荐