sphinx-apidoc picks up submodules, but autodoc doesn't document them

Question

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 )

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.

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

Baroda

Answer 1

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.

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. 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.

Baroda

Answer 2

I had a similar issue, that by changing the maxdepth of the toctree and rebuilding the html, nothing was changed in the visualization in the browser. I solved the issue by deleting first the concerned .rst files and rerun the sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …] command. After that, I rebuilt the html files by using make html. The visualization in the browser was than finally as it was desired.

Furcula