python - 使用 Sphinx 使用 :glob 生成 Python 文档：

Question

我是狮身人面像的新手。

该文件/home/user/myproject/docs/source/index.rst如下：

My project contents:

.. toctree::
   :glob:

   *

我在运行时收到以下$ make html消息/home/user/myproject/docs/：

checking consistency... /home/user/myproject/docs/source/design/index.rst:: WARNING: document isn't included in any toctree

我做错了什么？我希望 Sphinx 根据目录层次结构自动生成结构。

Answer 1

我不认为这是受支持的操作。

幸运的是，它也不是很理想，因为您通常希望文档的各个部分以特定的顺序出现。

Answer 2

如果您愿意在source没有文件夹层次结构的情况下转储所有源文件，这是可能的。或者，您可以编写一个例程并从Makefile调用sphinx-build.

正如迈克所提到的，:glob:只会按文件名的字母顺序拉入文件。请参阅此处的文档。

通过提供 glob 标志选项，您可以在 toctree 指令中使用“globbing”。然后将所有条目与可用文档列表进行匹配，并将匹配项按字母顺序插入列表中。

如果您想使用:glob:和维护所有文件的顺序，则source需要在.rst文件前面加上数字。

例子

source
├── index.html
├── 1_intro.rst
├── 2_install.rst
└── 3_more-than-you-want-to-know.rst

但是，如果您决定希望它们以不同的方式排列，您当然需要重命名文件，而不是将显式列表的顺序移动到index.rst.