如何使用 sphinx-apidoc 包含多个子目录？

Question

问题

\n

我正在尝试为包含许多子目录的 Python 项目构建文档。我正在尝试使用sphinx-apidoc以使该过程变得无缝。但是，尽管我尽了最大努力，但我无法处理子目录中的代码。我在这里遵循了 YouTube 上的一个很棒的简短教程，效果很好。为了模拟我遇到的问题，我将其中一个文件放入can_it_handle_folders目录中，如下所示。

\n

spamfilter-py\n\xe2\x94\x82   __init__.py  (**)\n\xe2\x94\x82   readme.md\n\xe2\x94\x82   sample.py\n\xe2\x94\x82   spamfilter.py\n\xe2\x94\x82   token.py\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80can_it_handle_folders\n\xe2\x94\x82       __init__.py\n\xe2\x94\x82       test_spamfilter.py\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80docs\n\xe2\x94\x82   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80build\n\xe2\x94\x82   \xe2\x94\x82   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80html\n\xe2\x94\x82   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80source\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80conf.py\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80index.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modules.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80sample.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80spamfilter.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80token.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80spamfilter-py.test_spamfilter.rst\n\xe2\x94\x82       \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80html\n...\n

\n

我进入该docs目录并运行sphinx-apidoc -o . ..以根据根spamfilter目录生成 .rst 文件。我已将以下行添加到conf.py：

\n

sys.path.insert(0, os.path.abspath(\'..\'))\n

\n

和我生成的modules.rst看起来像：

\n

spamfilter-py\n=============\n\n.. toctree::\n   :maxdepth: 4\n\n   sample\n   spamfilter\n   token\n

\n

目录中任何内容的 html 都can_it_handle_folders不会生成。如果我尝试添加can_it_handle_folders/test_spamfilter到目录树，我会得到一个toctree contains reference to nonexisting document \'can_it_handle_folders/test_spamfilter\'错误。

\n

问题

\n

我想要test_spamfilter模块显示在生成的 html 中。我该怎么做呢？设置此功能的最佳方法是什么？

\n

更新：这是初始化文件

\n

我已经隔离了该问题，该问题似乎位于__init__.py根目录中（上面标有 ** ）。我不知道如何处理这个问题。如果我删除它，sphinx 就会完全按照我想要的方式工作。如果我保留它，问题就变成了这里。看来这一定是一个问题sys.path。对于每个文件，这是我收到的错误：

\n

WARNING: invalid signature for automodule (\'spamfilter-py.can_it_handle_folders\')\nWARNING: don\'t know which module to import for autodocumenting \'spamfilter-py.can_it_handle_folders\' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)\n

\n

我已经尝试过以下内容conf.py：

\n

\n
• sys.path.insert(0, os.path.abspath(os.path.join(\'..\')))
\n
• sys.path.insert(0, os.path.abspath(os.path.join(\'..\', \'..\')))
\n
• sys.path.insert(0, os.path.abspath(os.path.join(\'..\', \'..\', \'..\')))
\n

\n

所有这些都导致了上面相同的错误消息。sphinx-apidoc -o ./source ../..除了跑步之外，我还尝试过跑步sphinx-apidoc -o ./source ..上面的每条路径可能是什么问题？我知道这一定是一些小配置的事情。

\n

语境

\n

我是 Sphinx 的绝对初学者。我尝试阅读文档，但它没有解决这个问题。我已经尝试了一些我认为明显不正确的事情。如果没有简单的答案，我将在此处添加我的尝试。我知道还有其他关于此的堆栈溢出问题，但它们不是最近的并且没有帮助。

\n

\n
• 使用 PowerShell 执行命令的 Windows 10 计算机
\n

\n

包含的文件：

\n

\n
• 索引.rst
\n

\n

Welcome to j\'s documentation!\n=============================\n\n.. toctree::\n   :maxdepth: 2\n   :caption: Contents:\n\n   modules\n\nIndices and tables\n==================\n\n* :ref:`genindex`\n* :ref:`modindex`\n* :ref:`search`\n

\n

\n
• .conf.py
\n

\n

spamfilter-py\n\xe2\x94\x82   __init__.py  (**)\n\xe2\x94\x82   readme.md\n\xe2\x94\x82   sample.py\n\xe2\x94\x82   spamfilter.py\n\xe2\x94\x82   token.py\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80can_it_handle_folders\n\xe2\x94\x82       __init__.py\n\xe2\x94\x82       test_spamfilter.py\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80docs\n\xe2\x94\x82   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80build\n\xe2\x94\x82   \xe2\x94\x82   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80html\n\xe2\x94\x82   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80source\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80conf.py\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80index.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modules.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80sample.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80spamfilter.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80token.rst\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80spamfilter-py.test_spamfilter.rst\n\xe2\x94\x82       \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80html\n...\n

\n

\n
• 第一个不起作用，spamfilter-py.rst：
\n

\n

spamfilter\\-py package\n======================\n\nSubpackages\n-----------\n\n.. toctree::\n   :maxdepth: 4\n\n   spamfilter-py.can_it_handle_folders\n\nSubmodules\n----------\n\nspamfilter\\-py.sample module\n----------------------------\n\n.. automodule:: spamfilter-py.sample\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\nspamfilter\\-py.spamfilter module\n--------------------------------\n\n.. automodule:: spamfilter-py.spamfilter\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\nspamfilter\\-py.token module\n---------------------------\n\n.. automodule:: spamfilter-py.token\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\nModule contents\n---------------\n\n.. automodule:: spamfilter-py\n   :members:\n   :undoc-members:\n   :show-inheritance:\n

\n

文档如下所示：\n

\n