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.pyfile 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.rstanddocs/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.rstfile to addmodulestaking 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 htmlinside thedocsfolder. 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 packageI'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.