I want to autogenerate documentation for a python project. I managed to get a barebones pipeline working with sphinx, but the output is not very pretty and I would appreciate some guidance on how to make the output cleaner and the inputs more maintainable.

My project is organized like so:

docs
   |-- build
   |-- index.rst
   |-- conf.py
app
   |-- main_app.py #entry point that intializes everything, internal imports in .py files are relative to here
   views
      |-- view1.py
      |-- view2.py
      |-- ...
   controllers
      |-- controller1.py
      |-- ...
   models
      |-- model1.py
      |-- ...
   utils
      |-- ...
   plugins
      |-- ...

Question 1
In my conf.py file, I had to mock the imports to get it to run, like so:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))
autodoc_mock_imports = ['utils', 'models','PySide6', 'controllers', 'views', 'configs']

This is, I believe, because the import statement in the .py files are written relative to the location of main_app.py, whereas the docs are generated from inside the docs folder. While this works, it feels like a hack that will come back to bite me at some point. Is there a more graceful way to handle this issue, without having to mock the imports?

Question 2

My table of contents is flat, like the below:

app
   app.controller.controller1
   app.models.model1
   app.utils.util1
   ...

I would prefer to have a table of contents with several nested levels that reproduces the folder structure of the app folder. How can I modify or redistribute my index.rst (below) to achieve this?

.. automodule:: app.utils.MetaReader
    :members:
...
.. automodule:: app.models.main_model
    :members:
...more automodule statements ...

.. toctree::
   :maxdepth: 4
   :caption: Contents:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Question 3
I would like to document “private” member functions for some classes, but not all. The internet pointed me to the :private-members:, but its use results in an error and no documentation being generated. I managed to get it working by setting the default behavior in conf.py:

extensions = ['sphinx.ext.autodoc']

autodoc_default_options = {
    "members": True,
    "undoc-members": False,
    "private-members": True}

but this applies universally and I do not want private members documented for all classes. How can I achieve this?