0

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 files docs/code.rst and docs/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 add modules 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 the docs 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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • I don't see anything obviously wrong. Many similar question have been asked before. For example: https://stackoverflow.com/q/57763542/407651, https://stackoverflow.com/q/50230797/407651, https://stackoverflow.com/q/41925973/407651 – mzjn Aug 22 '23 at 10:52
  • None of those solved my problem! – M. Merida-Floriano Aug 29 '23 at 08:41

0 Answers0