如何防止 sphinx 显示我的班级的完整路径？答案

【问题标题】：How can I prevent sphinx from displaying the full path to my class?如何防止 sphinx 显示我的班级的完整路径？
【发布时间】：2018-02-26 01:05:05
【问题描述】：

我有一个这样的项目结构：

package/
    __init__.py
    module.py

__init__.py 包含：

from .module import Class

module.py 包含：

class Class:
    pass

使用sphinx-apidoc -o package/docs/ package/ 和sphinx-build package/docs/ package/docs/_build，Class 的文档如下所示：

类 package.module.类

基础：对象

我想要这个输出：

类包。类

基础：对象

或者，更好的是，没有包名：

类类

基础：对象

用户不必知道类是在哪个文件中定义的；这些信息完全无关紧要，如果不是令人困惑的话。由于__init__.py 将Class 直接导入到包的命名空间中，因此用户会将此类导入为from package import Class，而不是from package.module import Class，我希望文档能够反映这一点。

有没有办法让 sphinx 输出相对于包的命名空间的路径？

【问题讨论】：

类似问题：stackoverflow.com/q/25276164/407651, stackoverflow.com/q/29385564/407651
@mzjn 这两个都询问从目录中删除模块名称；但我想解决方案 "write your own apidoc" 也适用于我的问题？这真的是唯一的方法吗？我很难相信这样一个常用的文档生成器没有“显示有用信息而不是无用信息”开关。
你看stackoverflow.com/a/42739816/407651了吗？看起来很有希望（但我还没有尝试过）。
@mzjn 是的，但据我所知，它只支持包和模块的模板。我可能遗漏了一些东西（我昨天才开始学习 sphinx），但是模块模板包含：{% for item in classes %} {{ item }}，所以我认为它不允许我自定义类的呈现方式。
一个快速且 UGLY 的解决方案是通过在目录树上应用正则表达式替换来对生成的文件进行后处理，类似于these 行

标签： python python-sphinx sphinx-apidoc

【解决方案1】：

尝试在 conf.py 中添加add_module_names = False

【讨论】：

【解决方案2】：

虽然添加add_module_names = False（请参阅this 答案）会使Sphinx 将package.module.Class 渲染为Class，但如果您想将package.module.Class 渲染为package.Class（即，将类记录为一部分），它并没有帮助package 命名空间）。

如果您希望 Sphinx 将 package.module.class 记录为 package.Class，请在包的 __init__.py 中包含以下行（请参阅 this 答案）：

# This lets you use package.module.Class as package.Class in your code.
from .module import Class

# This lets Sphinx know you want to document package.module.Class as package.Class.
__all__ = ['Class']

【讨论】：