Question

我一直致力于PyQt5的项目（在这里找到：https://github.com/MaVCArt/StyledPyQt5），该项目使用包结构使导入更合乎逻辑。到目前为止，我已经相对成功地使用Sphinx记录了代码，至少在我介绍包结构之前。（之前，一切都在一个文件夹中）

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

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

Answer 1

我最终解决了这个问题 - 似乎我忽略了一些错误，而且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分支来获取像我这样的文档，请不要忘记在主分支上单独生成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让我回到主分支

我知道有十几个教程可以记录这一点，但我希望这个小细节可能会在某些时候帮助某人。

sphinx-apidoc获取子模块，但autodoc不会记录它们

1 个答案: