使用Sphinx生成Python文档，使用:glob:。

Question

我是Sphinx新手。

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

My project contents:

.. toctree::
   :glob:

   *

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

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

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

- hllau

Answer 1

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

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

- Mike Graham

Answer 2

如果你愿意简单地将所有的源文件都倒入source而不使用文件夹层次结构，这是可行的。或者你可以编写一个例程，并在调用sphinx-build之前从Makefile运行它。

正如迈克所提到的，:glob:会按照文件名的字母顺序提取文件。在这里查看文档。

你可以在toctree指令中使用“globbing”，通过给出glob标志选项来实现。然后所有的条目都与可用文档列表进行匹配，匹配的内容按字母顺序插入列表中。

如果你想使用:glob:并保持所有文件在source中的顺序，你需要在.rst文件前面加上数字作为前缀。

示例

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

不过，如果您决定要以不同的顺序排序文件，而不是移动index.rst中显式列表的顺序，则当然需要重命名这些文件。

- ryanjdillon