sphinx-apidoc 拾取子模块，但 autodoc 没有记录它们答案

【问题标题】：sphinx-apidoc picks up submodules, but autodoc doesn't document themsphinx-apidoc 拾取子模块，但 autodoc 没有记录它们
【发布时间】：2016-12-17 12:40:48
【问题描述】：

我一直在为 PyQt5 开发一个项目（在此处找到：https://github.com/MaVCArt/StyledPyQt5），它使用包结构使导入更符合逻辑。到目前为止，我在使用 Sphinx 记录代码方面相对成功，至少在我介绍包结构之前是这样。（以前，所有东西都在一个文件夹中）

以下是问题：当我运行 sphinx-apidoc 时，一切运行正常，没有错误。更重要的是，autodoc 可以很好地提取我所有的子模块。这是我的一个 .rst 文件的内容：

styledpyqt package
==================

Subpackages
-----------

.. toctree::
    :maxdepth: 8

    styledpyqt.core

Submodules
----------

styledpyqt.StyleOptions module
------------------------------

.. automodule:: styledpyqt.StyleOptions
    :members:
    :undoc-members:
    :show-inheritance:

styledpyqt.StyleSheet module
----------------------------

.. automodule:: styledpyqt.StyleSheet
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: styledpyqt
    :members:
    :undoc-members:
    :show-inheritance:

如您所知，所有子模块都被拾取。

但是，当我对此运行 make html 时，这些模块都没有被记录（意味着标题在那里，但没有显示任何方法、类或成员）。在生成的 HTML 中，它们只是标题，下面没有任何内容。我知道它们在代码 cmets 中已正确设置，因为从现在到设置包结构（也就是文档确实起作用时），代码没有改变。

有人知道这可能是什么原因吗？

注意：为了帮助解决这个问题，以下是我的文件夹结构的简短细分：

styledpyqt
+    core
+    +    base
+    +    +    __init__.py ( containing a class definition )
+    +    +    AnimationGroups.py
+    +    +    Animations.py
+    +    __init__.py
+    +    Color.py
+    +    Float.py
+    +    Gradient.py
+    +    Int.py
+    +    String.py
+    __init__.py
+    StyleOptions.py
+    StyleSheet.py

【问题讨论】：

标签： python git pyqt5 python-sphinx autodoc

【解决方案1】：

我有一个类似的问题，通过更改目录树的最大深度并重建 html，浏览器中的可视化没有任何改变。我通过首先删除相关的 .rst 文件并重新运行 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …] 命令解决了这个问题。之后，我使用make html 重建了 html 文件。浏览器中的可视化效果最终达到了预期。

【讨论】：

【解决方案2】：

我最终解决了这个问题 - 似乎我忽略了一些错误，并且 sphinx 工作得很好。我在 conf.py 中添加了包中包含的所有路径，它只是从那里开始工作的：

conf.py:

sys.path.insert(0, os.path.abspath('../StyledPyQt5'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt/core'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt/core/base'))

从那里开始，一切正常。

请务必注意，我在与代码不同的目录中生成文档。如果您使用 sphinx-apidoc 生成 .rst 文件，并且像我一样使用 gh-pages 分支来生成文档，请不要忘记在 master 分支上单独生成 HTML 页面。否则，将没有任何代码可供来源。我的工作流程现在看起来像这样：

通过运行git checkout master 确保我在主分支上
运行sphinx-apidoc -F -P -o ..output_dir ..source_dir，其中 output_dir 与 source_dir 不同。
运行 make html，确保 _build/html 位于我的仓库的任一分支中都不存在的目录中。
运行 git checkout gh-pages 切换到我的 gh-pages 分支，删除代码文件并用 html 文档页面替换它们。
将 _build/html 中所有新生成的 HTML 文件复制到 gh-pages 主文件夹，覆盖所有更改。
运行 git commit -am "Docs Update" gh-pages 提交更改
运行 git push origin gh-pages 将提交推送到 github
运行 git checkout master 让我回到主分支

我知道有十几个教程记录了这一点，但我希望这个小小的阐述可能会在某个时候对某人有所帮助。

【讨论】：