My code has the following structure:
.
└── my_package
├── __init__.py
├── classif
│ ├── __init__.py
│ ├── inference.py
│ └── models.py
├── datasets
│ ├── __init__.py
│ └── datasets.py
└── matching
├── __init__.py
├── elastic.py
└── search.py
After a sphinx-quickstart (with autodoc) I ran sphinx-apidoc as follows:
sphinx-apidoc -f -o source my_package -e -M
I now have the following files:
.
├── Makefile
├── build
├── my_package
│ ├── __init__.py
│ ├── __pycache__
│ ├── classif
│ ├── datasets
│ └── matching
└── source
├── _static
├── _templates
├── conf.py
├── index.rst
├── modules.rst
├── my_package.classif.inference.rst
├── my_package.classif.models.rst
├── my_package.classif.rst
├── my_package.datasets.datasets.rst
├── my_package.datasets.rst
├── my_package.matching.elastic.rst
├── my_package.matching.rst
├── my_package.matching.search.rst
└── my_package.rst
I also modified conf.py to add:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('..'))
and added modules to the index.rst:
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
# [more lines]
After running make clean ; make html I get the warnings:
/path/to/my_package.classif.rst: WARNING: document isn't included in any toctree
/path/to/my_package.datasets.rst: WARNING: document isn't included in any toctree
/path/to/my_package.matching.rst: WARNING: document isn't included in any toctree
Which makes sense as sphinx-apidoc did not reference them in my_package.rst. How can I solve this?
The issue was actually known -> https://github.com/sphinx-doc/sphinx/issues/4446
Upgrading to sphinx 1.7.6 solved it.