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 infoconf.py
file, adding sphinx.ext.autodoc
, sphinx.ext.napoleon
as well as a sys.path.abspath(..)
(shortened)sphinx-apidoc
on my 3 different folders in many different ways.rst
files in subdirectories in my main docs directoryindex.rst
and/or modules.rst
and adding the names of my folders/files to themI'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!
After trying pretty much everything, I solved it by:
sphinx-quickstart
, made sure to separate build and sourceproject
had a __init__.py
filedocs/source
folder, edited my conf.py
file and addedimport os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', 'project'))
sys.path.insert(0, basedir)
sphinx.ext.autodoc
and sphinx.ext.napoleon
to the extensionsmodules
under the toctree directive in index.rst
sphinx-apidoc -o ./source ../project -f --separate
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