我一直在为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中，它们只是标题，下面没有任何内容。我知道一个事实，他们正确地设置在代码注释中，因为代码从现在到设置包结构之间没有改变，也就是当文档工作时。
有人知道这可能是什么原因吗?
注意:为了帮助解决这个问题，下面是我的文件夹结构的简短细分:
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
我最终解决了这个问题-似乎我忽略了一些错误，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文件，并且像我一样使用高页面分支来生成文档，那么在使用主分支时，不要忘记单独生成HTML页面。否则，将没有任何源代码。我的工作流程现在是这样的:
- 确保我在主分支上运行
git checkout master - 运行
sphinx-apidoc -F -P -o ..output_dir ..source_dir，其中output_dir与source_dir不同。 - 运行
make html，确保_build/html在一个不在我的repo分支的目录中。 - 运行
git checkout gh-pages切换到我的h-pages分支，删除代码文件并将其替换为html文档页。 - 将_build/HTML中所有新生成的HTML文件复制到h-pages主文件夹中，覆盖任何更改。
- 运行
git commit -am "Docs Update" gh-pages提交更改 - 运行
git push origin gh-pages将提交推送到github - 运行
git checkout master将我放回主分支
我知道有很多教程都在记录这个，但我希望这个小小的阐述可以在某个时候帮助到别人。
我有一个类似的问题，通过改变toctree的maxdepth和重建html，在浏览器中的可视化没有任何改变。我通过首先删除有关的.rst文件并重新运行sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]命令来解决这个问题。之后，我用make html重建了html文件。浏览器中的可视化效果最终达到了预期的效果。