sphinx-apidoc拾取子模块，但是autodoc不会记录它们 [英] sphinx-apidoc picks up submodules, but autodoc doesn't document them

问题描述

我一直在为PyQt5设计一个项目(在这里找到: https://github.com/MaVCArt/StyledPyQt5 )，它使用包结构使导入更加合理.到目前为止，我在使用Sphinx记录代码方面一直比较成功，至少直到介绍了包结构为止.(之前，所有内容都在一个文件夹中)

I've been working on a project for PyQt5 ( found here: https://github.com/MaVCArt/StyledPyQt5 ) which uses a package structure to make imports a bit more logical. I've been relatively successful in documenting the code so far with Sphinx, at least up until I introduced the package structure. ( before, everything was in one folder )

以下是问题所在:当我运行sphinx-apidoc时，一切运行正常，没有错误.而且，autodoc可以很好地拾取我的所有子模块.这是我的.rst文件之一的内容:

The following is the problem: when I run sphinx-apidoc, everything runs fine, no errors. What's more, autodoc picks up all my submodules just fine. This is the content of one of my .rst files:

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:

您可以看到，所有子模块都已被拾取.

As you can tell, all submodules are being picked up.

但是，当我在其上运行make html时，没有记录这些模块(这意味着标题在那里，但未显示任何方法，类或成员).在生成的HTML中，它们只是标头，下面没有任何内容.我知道一个事实，即它们在代码注释中的设置正确，因为从现在到包结构的设置(也就是文档生效时)之间，代码没有更改.

However, when I run make html on this, none of these modules are being documented ( meaning the headers are there, but none of the methods, classes or members are displayed ). In the generated HTML, they're just headers with nothing underneath. I know for a fact that they're properly set up in the code comments, as the code has not changed between now and the set up of the package structure, aka when the documentation did work.

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

Does anyone have any ideas what the cause of this might be?

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

Note: to help with resolving this, here's a short breakdown of my folder structure:

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

推荐答案

我最终解决了这个问题-似乎我忽略了一些错误，狮身人面像工作得很好.我在conf.py中添加了软件包包含的所有路径，并且从那里开始就可以使用了:

I ended up fixing this problem eventually - it seems I was overlooking some errors, and sphinx worked just fine. I added all the paths the package contains in the conf.py and it just worked from there:

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'))

从那里开始，一切正常.

From there, everything worked.

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

It's important to note here that I generate my docs in a separate directory from my code. If you're using sphinx-apidoc to generate your .rst files, and you're using a gh-pages branch for documentation like I am, don't forget to generate your HTML pages separately while you're on the master branch. Otherwise, there won't be any code to source from. My workflow looks like this now:

1. 通过运行 git checkout master
来确保我在master分支上
2. 运行 sphinx-apidoc -F -P -o ..output_dir ..source_dir ，其中output_dir与source_dir不同.
3. 运行 make html ，确保_build/html位于目录中，而该目录不在我的仓库中.
4. 运行 git checkout gh-pages 切换到我的gh-pages分支，删除代码文件并将其替换为html文档页面.
5. 将_build/html中所有新生成的HTML文件复制到gh-pages主文件夹中，覆盖所有更改.
6. 运行 git commit -am文档更新" gh-pages 提交更改
7. 运行 git push origin gh-pages 将提交推送到github
8. 运行 git checkout master 让我回到master分支

1. make sure i'm on the master branch by running git checkout master
2. run sphinx-apidoc -F -P -o ..output_dir ..source_dir, where output_dir is not the same as source_dir.
3. run make html, making sure that _build/html is in a directory that isn't in either branch of my repo.
4. run git checkout gh-pages to switch to my gh-pages branch, removing code files and replacing them with html documentation pages.
5. copy all newly generated HTML files in _build/html to the gh-pages main folder, overwriting any changes.
6. run git commit -am "Docs Update" gh-pages to commit the changes
7. run git push origin gh-pages to push the commit to github
8. run git checkout master to put me back on the master branch

我知道那里有一毛钱的教程可以证明这一点，但是我希望这种细微的阐述可以在某个时候对某人有所帮助.

I know there's a dime a dozen tutorials out there documenting this, but I hope this small elaboration might help someone at some point.

这篇关于sphinx-apidoc拾取子模块，但是autodoc不会记录它们的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！