I'm doing a really simple example and can't get it to work. I just have one file, simulator.py
that I added numpy style docstrings to. It does not import any other libraries. It has an __init__
and I can import it from a python interpreter. My directory structure is as follows:
|__ modules
|__ __init__.py
|__ simulator
| |__ simulator.py
|__ docs
|__ Makefile
|__ _static
|__ conf.py
|__ index.rst
|__ modules.rst
|__ _build
|__ _templates
|__ simulator.rst
|__ make.bat
I'm using sphinx-build 4.0.2. I pip installed sphinxcontrib-napoleon even though sphinx-ext.napoleon is supposed to be included in later versions of sphinx.
In my conf.py, I have
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
and
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon'
]
To make my .rst
files I run sphinx-apidoc -f --ext-autodoc -o . ../simulator
from the docs
directory. It creates modules.rst
and simulator.rst
. I added 'modules' to the toctree in index.rst
, and 'simulator' is in the toctree that was autobuilt in modules.rst
.
It creates a heading in each file and a toctree. No docstrings. I read that it just creates the model to build the html from the docstrings, so I ran make html
. It builds with just the table of contents, nothing from the docstrings. What could be going wrong? I've tried different variations of the path.insert()
command even though I'm pretty sure what I have is correct. I've tried moving simulator.py
into the main directory, I've tried adding a bunch of other random crap from examply conf.py
files I've found from searching other solutions to this issue. None of the solutions have worked.
I think the problem comes from sys.path.insert(0, os.path.abspath('..'))
. You're actually adding modules
to the Python path, so import simulator
would import modules/simulator
and not modules/simulator/simulator
as you would like.
You should rather do:
|__ modules
|__ simulator
| |__ __init__.py
| |__ simulator.py
|__ docs
|__ ...
and change your conf.py
to:
sys.path.insert(0, os.path.abspath('../simulator'))