pythonpython-sphinxautodoc

Generating documentation for multiple folders with Sphinx


I am currently working on a Python project that is growing bigger than expected.
My code is documented all throughout with docstrings, and I would now like to generate a comprehensive documentation with Sphinx.
However, no matter what I try, I can't figure out a way to generate everything in a single command.

Here is the updated structure of my project:

.
├── docs
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
├── project
│   ├── module1
│   │   ├── file1.py
│   │   └── file2.py
│   ├── ext_files
│   │   └── >files we dont care about
│   ├── module2
│   │   ├── file3.py
│   │   ├── file4.py
│   │   └── file5.py
│   ├── module3
│   │   ├── file6.py
│   │   ├── file7.py
│   │   ├── file8.py
│   │   └── file9.py
│   └── main.py
├── README.md
└── requirements.txt

Ideally, I would like an HTML documentation that follows this structure.

What I've tried:

I've also tried manually adding automodule directives, as well as creating submodules.
I've tried setting up sphinx-autogen to discover my different modules automatically.
However, no matter what I do, it either only generates documentation for my main.py file or nothing at all.

Please help me, as I am going crazy. No matter what tutorial I follow or documentation I read, I can't seem to find an answer.
Thanks in advance!


Solution

  • After trying pretty much everything, I solved it by:

    1. Updating my project structure to reflect the one above (inspired by the link given by Lex Li)
    2. Deleted all my sphinx files, re-ran sphinx-quickstart, made sure to separate build and source
    3. Made sure every subfolder of project had a __init__.py file
    4. From the docs/source folder, edited my conf.py file and added
    import os
    import sys
    basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', 'project'))
    sys.path.insert(0, basedir)
    
    1. Added sphinx.ext.autodoc and sphinx.ext.napoleon to the extensions
    2. Added modules under the toctree directive in index.rst
    3. From the docs folder, ran sphinx-apidoc -o ./source ../project -f --separate
    4. Then, from docs/, ran make html.

    After running sphinx-apidoc, make sure a <module>.rst file is generated for each module you have or need documented.

    I feel like this detailed answer could be useful to someone, as it is somewhat the compilation of multiple StackOverflow answers.

    Please note that my project directory looks like this:

    .
    ├── docs
    │   ├── build
    │   └── source
    ├── project
    │   ├── module1
    │   ├── module2
    │   ├── module3
    └── └── module4
    └── tests