Sphinx apidoc - 不打印包和模块的完整路径

Question

我刚接触sphinx，想用它来为我的项目生成API参考文档。之后可能还会用它来做项目的其他文档。

我用这两个命令生成文档：

sphinx-apidoc -e -o doc/api tracer
sphinx-build -b dirhtml doc/ build/doc/dirhtml

但是出现了一个问题，它生成的目录看起来很糟糕：

- tracer package
    - tracer.lang package
        - tracer.lang.en module
    - tracer.packageManagers package
        - tracer.packageManagers.dnf module
        - tracer.packageManagers.dpkg module
        - tracer.packageManagers.portage module
        - ...
    - tracer.resources package
        - tracer.resources.ProcessesList module
        - tracer.resources.applications module
        - tracer.resources.args_parser module
        - ...

这个列表很不清晰，因为里面有很多多余的信息。如果能这样显示就好了：

- tracer package
    - lang package
        - en module
    - packageManagers package
        - dnf module
        - dpkg module
        - portage module
        - ...
    - resources package
        - ProcessesList module
        - applications module
        - args_parser module
        - ...

或者甚至可以去掉最后的package或module标签，这样会更好。

总之，哪里都看起来不太好。例如：

class tracer.packageManagers.portage.Portage
    Bases: tracer.packageManagers.ipackageManager.IPackageManager

如果能这样显示就会好很多：

class Portage
    Bases: IPackageManager

我知道在大型项目中，完整的名称可能比较好，因为模块名可能会重复，但在我这个小项目里我不太喜欢这样。请问我能否告诉apidoc生成简短的名称呢？

能帮我一下吗？

非常感谢，
FrostyX

Answer 1

关于目录的内容，我发现对所有的 *.rst 文件进行搜索和替换是最终解决我问题的方法（在运行 sphinx-apidoc 之后）。

搜索内容：

^(?:[a-zA-Z0-9]*[.])*([a-zA-Z0-9]+) (package|module)

替换为：

\1 \2

...这样可以缩短标题，这个标题会显示在目录树中。唯一的影响是该模块页面上的标题也会变成短名称，但这对我来说没什么问题，因为导航和目录内容仍然清楚地表明了父包是什么。

至于类和函数的名称，mzjin 在评论中提到：

在 conf.py 文件中设置 add_module_names = False

这样就可以解决问题了。