Generating documentation for multiple folders with Sphinx

Question

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:

sphinx-quickstart, giving proper info
Then editing the conf.py file, adding sphinx.ext.autodoc, sphinx.ext.napoleon as well as a sys.path.abspath(..) (shortened)
Using sphinx-apidoc on my 3 different folders in many different ways
Moving around the .rst files in subdirectories in my main docs directory
Modifying the index.rst and/or modules.rst and adding the names of my folders/files to them

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!

Asked By: Koreos

||

Source

Answer 1

After trying pretty much everything, I solved it by:

Updating my project structure to reflect the one above (inspired by the link given by Lex Li)
Deleted all my sphinx files, re-ran sphinx-quickstart, made sure to separate build and source
Made sure every subfolder of project had a __init__.py file
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)

Added sphinx.ext.autodoc and sphinx.ext.napoleon to the extensions
Added modules under the toctree directive in index.rst
From the docs folder, ran sphinx-apidoc -o ./source ../project -f --separate
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

Answered By: Koreos

Generating documentation for multiple folders with Sphinx

Question:

Answers: