为`sphinx-apidoc`自定义模板

问题描述

我最近尝试使用sphinx-apidocfromSphinx来帮助从一个Python项目的API生成特定于Sphinx的reStrutiredText。

但是，我得到的结果是：

谁知道我是否可以自定义sphinx-api用于其输出的模板？具体地说，我想：

• 去掉所有"子模块"、"子包"和"模块内容"标题，
• 让我的__init__.py文件中的docstring结果直接显示在包的下面，这样当我单击包名称时，首先看到的就是包文档。目前，本文档放在每个程序包部分末尾略显奇怪的"模块内容"标题下。

我认为"子模块"和"子包"标题是多余的，因为包/模块的正常标题是"xxx.yyy包"和"xxx.yyy.zzz模块"。

我希望上面的小示例的结构是

• orexplore.ents包
  • orexplore.Components.mbg120模块
• orexplore.模拟器包
  • orexplore.simators.test包
    • orexplore.simators.est.mbg120模块
  • orexplore.simators.mbg120模块

在单击包的位置，我在页面上首先看到的将是包文档。

或者甚至只是

• orexplore.组件
  • orexplore.Components.mbg120
• orexplore.模拟器
  • orexplore.simators.test
    • orexplore.simators.est.mbg120
• orexplore.simators.mbg120

如果有某种方法可以从视觉上区分封装/模块(颜色？徽章？)而不是冗长的"包"和"模块"。

---

解决方案

sphinx-apidoc脚本使用apidoc.py模块。我不能提供详细的说明，但为了删除标题或以其他方式定制输出，您必须编写此模块的您自己的版本。没有其他"；模板"；。

注意，如果API和模块结构稳定，则不需要重复运行sphinx-apidoc。您可以根据自己的喜好对生成的rst文件进行一次后处理，然后将它们置于版本控制之下。另请参阅https://stackoverflow.com/a/28481785/407651。

更新

从Sphinx 2.2.0开始，sphinx-apidoc支持模板。请参阅https://stackoverflow.com/a/57520238/407651。