sphinx-apidoc 中的 module.rst 是什么？

Question

我正在使用

sphinx==6.2.1

和

sphinx_rtd_theme==1.3.0

。我运行了

sphinx-apidoc

，它生成了一个

modules.rst

，如下所示：

package
======

.. toctree::
   :maxdepth: 4

   package

当我去跑步

sphinx-build docs docs/_build

时，我收到警告：

checking consistency... /Users/user/code/package/docs/modules.rst: WARNING: document isn't included in any toctree

我尝试删除

modules.rst

，但它不断被

sphinx-apidoc

重新生成。

modules.rst

应该如何使用，以及它应该如何与

index.rst

联系起来？

sphinx-apidoc

的意图是什么？

我正在尝试以 Sphinx 标准方式解决此警告。

Answer 1

这与你的文档结构有关。

modules.rst

由一个目录树组成，该目录树链接到与每个 python 文件关联的每个第一个文件。使用

modules.rst

，您的文档可以 看起来像这样：

docs/
|_ _build/
|_ _static/
|_ _templates/
|_ source/
|  |_ bar.rst
|  |_ conf.py
|  |_ index.rst
|  |_ foo.rst
|  |_ modules.rst
|  |_ usage.rst
|_ Makefile
|_ make.bat

在index.rst内：

Welcome to <project> documentation!
==================================

<welcome text>

Contents
--------

.. toctree:: 
   :maxdepth: 2
   :caption: Usage

   usage

.. toctree::
   :maxdepth: 2
   :caption: Documentation

   modules

这将链接到

modules.rst

文件，其中包含

foo

和

bar

。