为什么 autoclass 会在这里创建别名？

如何解决为什么 autoclass 会在这里创建别名？

简而言之，我有可以运行的代码，但如果我稍作调整，有些事情就会崩溃，我似乎无法弄清楚原因。我希望比我更有经验的人可以给我一些 Sphinx 指点。我已经搜索过了，之前没有看到过类似这个问题的帖子。

有用的东西

我有包含模块 my_pkg 的包 mod，其中包含许多类和函数。

如果我在 conf.py

中使用以下行

sys.path.insert(0,os.path.abspath('../my_pkg'))

我的 .rst 文件之一包含以下内容

.. 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 中所述。