Sphinx doesn't process python classes

Question

Gooday, I'm having trouble at autogenerating python documentation. My project layout is the following:

project_folder

package
- module1.py
- module2.py
doc
- make.bat
- build
- source
  - index.rst
  - package.rst
  - modules.rst
  - conf.py

inside module1.py and module2.py there are some classes (with docstrings). I've added in conf.py the following line:

sys.path.insert(0, os.path.abspath('../../package'))

both modules.rst and package.rst have been generating by calling:

sphinx-apidoc -o doc/source package/

inside the folder. Finally, I've added "modules" inside the index.rst file as displayed below (not the whole index.rst, but it was generated by sphinx-quickstart):

Contents:

.. toctree::
   :maxdepth: 2

   modules

I have several issues:

1) when I call sphinx-autodoc from doc/ directory the documentation isn't generated. In order to correctly generate the documentaiton, I have to replace package.module1 with module1 inside package.rst:

#before
.. automodule:: package.module1
    :members:
    :undoc-members:
    :show-inheritance:
#after
.. automodule:: module1
    :members:
    :undoc-members:
    :show-inheritance:

How can I automatically perform this operation? Or is my setup faulty?

2) If module1.py contains only a bunch of defs, the documentation is generated correctly. However, if I put only a class inside it, the documentation isn't generated at all (note that package.rst file remains unchanged even after running a second time a sphinx-apidoc). What can I do to display class documentation?

Thanks

score 3 · Accepted Answer · answered Jul 18 '15 at 12:15

Ok, after viewing sphinx logs (my bad for not posting them out) I realized the answer for the first issue: if you want to use the sphinx-apidoc output you have to add in conf.py the parent of "Package" package, not package itself

sys.path.insert(0, os.path.abspath('../../')) #documentation is detected
sys.path.insert(0, os.path.abspath('../../package')) #documentation isn't detected

In this way python import the folder in PYTHONPATH, thereby solving the "Package.module1"/"Package.module2" path. As for the issue #2, I realized (again, my bad) sphinx generated documentation only for public members and my class had only dunder methods (like __ init__). If you want to document those methods (like me), be sure to add in the .rst files :special-members: under the module loaded:

.. automodule:: Package.module2
    :members:
    :undoc-members:
    :show-inheritance:
    :private-members: # if you want to document __x attributes
    :special-members: # if you want to document __xxx__ dunder methods

Sphinx doesn't process python classes

1 Answers1