您可以仅使用 sphinx-apidoc 自动记录子模块吗？

问题描述

我为我的点击应用程序使用 sphinx-click 扩展，我想使用 sphinx-apidoc 为 only 子模块生成 .rst 文件。

我已经使用 python Sphinx 文档库大约一年了，我有一个用例......我不太清楚......也许我现在只是瞎了。

无论如何，我有一个结构类似于

的cli工具

my_tool/
+-- __init__.py
+-- cli_entry.py
+-- utils
|   +-- __init__.py
|   +-- foo.py
|   +-- bar.py

其中 cli_entry 是一个点击应用程序，它导入 my_tool.utils.foo 和 my_tools.utils.bar 因为这是使用 Click 库。我决定使用 sphinx_click 扩展来记录 cli_entry.py 中的任何命令（它记录了所有很棒的命令）。

但问题是，我想使用 sphinx-apidoc 为 ./my_tool/utils/ 模块中的所有内容生成 .rst 文件。当我将命令用作 sphinx-apidoc -o ../docs/utils my_tool/utils 时，我得到的输出文件包括

docs/
+-- utils
|   +-- module.rst
|   +-- utils.rst

一开始看起来不错，但打开 utils.rst 后，文件看起来像

utils package
=============

Submodules
----------

utils.foo module
----------------------

.. automodule:: utils.foo
   :members:
   :undoc-members:
   :show-inheritance:

utils.bar module
----------------------

.. automodule:: utils.bar
   :members:
   :undoc-members:
   :show-inheritance:

然后，当我使用 make html（来自 sphinx 生成的 makefile）构建文档时，我收到一条错误消息，指出 Failed to import 'utils.foo': no module named utils.foo 那是因为导入应该以 my_tool.utils.foo 的形式存在

如何使用 sphinx-apidoc 仅生成子模块并且包含正确的导入路径？？也许它是我在 conf.py 中缺少的东西......也许它是我在 sphinx-apidoc 中缺少的一个选项？

编辑：我应该提到我可以使用 exclude_pattern 参数......但我宁愿不必在我的根目录中指定每个 cli 文件。前任。如果我有 cli_entry.py，cli_commandgroup1.py ... cli_commandgroupN.py。我希望这个解决方案足够动态，只支持子模块。

编辑：我尝试使用 sphinx-apidoc -o ../docs/utils my_tool/ 并创建以下输出

docs/
+-- utils
|   +-- module.rst
|   +-- my_tool.cli_entry.rst
|   +-- my_tool.utils.rst

现在在 my_tool.utils.rst 文件中，导入正确，可以生成文档。

my_tool.utils.foo module
----------------------

.. automodule:: my_tool.utils.foo
   :members:
   :undoc-members:
   :show-inheritance:

指定 my_tool/ 的问题是 my_tool.cli_entry.rst 被创建，而这个 .rst 文件已经使用 click-sphinx 扩展名创建。

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

python python-sphinx sphinx-apidoc