使用 Sphinx 使用 :glob 生成 Python 文檔：

Question

我是斯芬克斯的新手。

文件/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 根據目錄層次結構自動生成結構。

Answer 1

我認為這不是受支持的操作。

幸運的是，它也不是很理想，因為您通常希望文檔的各個部分以特定的順序出現。

Answer 2

如果您願意在沒有文件夾層次結構的情況下將所有源文件轉儲到source ，這是可能的。 或者，您可以編寫一個例程並在調用sphinx-build之前從Makefile運行它。

正如邁克所暗示的， :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顯式列表的index.rst 。