I am using sphinx==6.2.1 and sphinx_rtd_theme==1.3.0. I ran sphinx-apidoc, and it generated a modules.rst that looks like this:
package
======
.. toctree::
:maxdepth: 4
package
When I go to run sphinx-build docs docs/_build, I get a warning:
checking consistency... /Users/user/code/package/docs/modules.rst: WARNING: document isn't included in any toctree
I tried deleting modules.rst, but it keeps getting regenerated by sphinx-apidoc.
How is modules.rst supposed to be used, and how should it have been linked with index.rst? What is it's intent within sphinx-apidoc?
I am trying to resolve this warning in a Sphinx-standard way.
This is related to the structure of your documentation. modules.rst consists of a toctree that links to each of the rst files associated with each python file. Using modules.rst, your documentation could look like so:
docs/
|_ _build/
|_ _static/
|_ _templates/
|_ source/
| |_ bar.rst
| |_ conf.py
| |_ index.rst
| |_ foo.rst
| |_ modules.rst
| |_ usage.rst
|_ Makefile
|_ make.bat
Within index.rst:
Welcome to <project> documentation!
==================================
<welcome text>
Contents
--------
.. toctree::
:maxdepth: 2
:caption: Usage
usage
.. toctree::
:maxdepth: 2
:caption: Documentation
modules
This would link to the modules.rst file, which would contain both foo and bar.