I'm trying to generate my project documentation using Sphinx 6.2.1 and Python3. I'm working with a test project named sphinx-basic-test
. I've created a docs
folder and run sphinx-quickstart
inside. So far, my project structure is:
sphinx-basic-test
-code
|__ __init__.py
|__ classifiers.py (several functions)
|__ clean_data.py (a class, with main method)
|__ data_tools.py (several functions)
- docs
|__ Makefile
|__ _build
|__ _static
|__ _templates
|__ conf.py
|__ index.rst
|__ make.bat
I've followed several tutorials, stackoverflows threads and official documentation:
- I've modified
conf.py
file adding the following lines:
import sys
sys.path.insert(0, os.path.abspath('..'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']
- I've then run the line:
sphinx-apidoc -o docs code/
in the root folder (sphinx-basic-test
). And it has created filesdocs/code.rst
anddocs/modules.rst
. Content of the first one is:
code package
============
Submodules
----------
code.classifiers module
-----------------------
.. automodule:: code.classifiers
:members:
:undoc-members:
:show-inheritance:
code.clean\_data module
-----------------------
.. automodule:: code.clean_data
:members:
:undoc-members:
:show-inheritance:
code.data\_tools module
-----------------------
.. automodule:: code.data_tools
:members:
:undoc-members:
:show-inheritance:
And the content of the second one is simply:
code
====
.. toctree::
:maxdepth: 4
code
- I've modified
index.rst
file to addmodules
taking care of identation:
Welcome to test's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
After doing this, I've run
make html
inside thedocs
folder. This rise a lot of warnings, all of the type:WARNING: autodoc: failed to import module 'classifiers' from module 'code'; the following exception was raised: No module named 'code.classifiers'; 'code' is not a package
I've checked the created html file and it does display the name of the different functions and class (but not the methods inside the class), but not documentation is generated. I've tried several things so far, including changing the abs.path in configuration file, with no different output.
The only different result I've get is without using
sphinx-apidoc
, and just writing blocks like:
.. automodule:: classifiers
:members:
in index.rst
file. But this only works with one of the script, if I try to also add clean_data
this way, it won't work.
I would like to create html files so all three scripts are documented using docstring in the python files, together with additional information I'd like to add. But I'm stuck in the first goal, any help is appreciated.