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

- FrostyX

---

如果在conf.py中设置add_module_names = False，是否有效？请参见http://sphinx-doc.org/config.html#confval-add_module_names。 - mzjn

谢谢，它确实有些帮助。现在看起来像这样：`class Portage Bases: tracer.packageManagers.ipackageManager.IPackageManager` 但在其他地方，还有完整的名称。 - FrostyX

Answer 1

就目录而言，在运行sphinx-apidoc之后，在源文件夹中对所有*.rst文件执行搜索/替换是最终适用于我的方法。

搜索：

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

替换：

\1 \2

...这会缩短标题，显示在toctree中。唯一的后果是该模块页面上的标题也将成为短名称，但这并不影响我，因为导航和目录仍然清楚地显示父包的内容。

至于类/函数名称，根据mzjin对问题的评论:

  

在conf.py中设置add_module_names = False就可以解决问题。

就可以解决问题了。

- Ryan de Kleer