问题
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
回答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:
- make sure i'm on the master branch by running
git checkout master
- run
sphinx-apidoc -F -P -o ..output_dir ..source_dir
, where output_dir is not the same as source_dir. - run
make html
, making sure that _build/html is in a directory that isn't in either branch of my repo. - run
git checkout gh-pages
to switch to my gh-pages branch, removing code files and replacing them with html documentation pages. - copy all newly generated HTML files in _build/html to the gh-pages main folder, overwriting any changes.
- run
git commit -am "Docs Update" gh-pages
to commit the changes - run
git push origin gh-pages
to push the commit to github - 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.
来源:https://stackoverflow.com/questions/38885106/sphinx-apidoc-picks-up-submodules-but-autodoc-doesnt-document-them