Sphinx autodoc/napoleon doesn't generate docstrings

Question

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.

Answer 1

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'))