问题描述
简而言之,我有可以运行的代码,但如果我稍作调整,有些事情就会崩溃,我似乎无法弄清楚原因。我希望比我更有经验的人可以给我一些 Sphinx 指点。我已经搜索过了,之前没有看到过类似这个问题的帖子。
有用的东西
我有包含模块 my_pkg
的包 mod
,其中包含许多类和函数。
如果我在 conf.py
sys.path.insert(0,os.path.abspath('../my_pkg'))
.. automodule:: mod
.. autoclass:: mod.classA
:members:
.. autofunction:: mod.functionA
.. autoclass:: mod.classB
:members:
然后当我运行我的文档时一切正常!但是,这些将输出文档中的调用签名呈现为 mod.classA(例如),我宁愿它们呈现为 my_pkg.mod.classA。
没用的东西
要进行此更改,我认为我应该像这样从 conf.py
中删除 pkg
sys.path.insert(0,os.path.abspath('../my_pkg'))
然后将我的 .rst 文件更改为从 pkg 开始查找,如下所示:
.. automodule:: my_pkg.mod
.. autoclass:: my_pkg.mod.classA
:members:
.. autofunction:: my_pkg.mod.functionA
.. autoclass:: my_pkg.mod.classB
:members:
如果我这样做,automodule 指令不会处理任何内容,因此不会显示我的模块的文档字符串(我没有收到关于 autodoc 无法找到 pkg.mod 的任何警告,所以我觉得这很奇怪)。输出为
.. autoclass:: my_pkg.mod.classA
:members:
只是 alias of my_pkg.mod.
... 即使这是错误的。尽管如此,类签名中的“源”按钮正确链接到该类的代码。最后,剩余的函数和类按照我的要求精确呈现。看起来 Sphinx 出于某种原因真的不想记录这个模块或 classA。
这个问题让我发疯。它发生在多个主题中,所以我相信这是一个 Sphinx 问题。我已经尝试将 classA 的文档字符串更改为 """foo"""。我试过在文档中移动 classA,所以它不是真正代码的第一位。我试过重命名classA。似乎没有什么可以解决它,而 classA 始终是问题所在。
有谁知道为什么会发生这种情况?我使用的是 Sphinx v4.1.1 和 sphinx-rtd-theme v0.5.2(撰写本文时两者的最新版本)。
解决方法
编辑:我最初的想法是完全错误的,但我现在已经能够多次重现该问题。 mzjn 是正确的,我没有提供足够的上下文。
这个问题似乎是由 my_pkg
被模拟导入引起的。在 conf.py
我有一条线
autodoc_mock_imports = ['my_pkg','numpy','scipy','pandas']
我的发现是,如果我尝试从包根目录开始记录(即 my_pkg
是 automodule 和 autoclass 的第一个参数,如无效部分中所述)和 my_pkg
是一个模拟导入,Sphinx 会导致我上面描述的问题。我忘记在更改结构时从模拟导入中删除 my_pkg
(这仍然不能真正解释为什么存在这种行为,但至少我找到了如何重现它)。
您可能需要为您的类/函数定义 __module__
属性,如 another Stack Overflow post 中所述。