如何在sphinx項目中正確包含其他ReST文件？

Question

我的手寫文檔/用戶指南（用Sphinx編寫在ReStructuredText中）已經變得相當大，所以我開始在子目錄中組織我的.rst文件。

在index.rst我包括每個子目錄的subindex.rst，其本身包括其他.rst文件的其他子目錄。

index.rst：

.. include:: subdir1/subindex.rst 
.. include:: subdir2/subindex.rst 

subdir1/subindex.rst：

.. include:: file1.rst 
.. include:: file2.rst 

原則上這個運作良好，除了那個獅身人面像遞歸尋找它試圖解析.rst -files。而無需更改當前工作目錄。因此，在subdir1內看到include:: file1.rst時失敗。

我正在通過設置exclude_pattern來解決此問題，以忽略我的子目錄。這似乎是不正確的。

什麼是包含.rst子文件的正確方法？

Answer 1

toctree directive應該做你想做的。

.. toctree:: 
    :glob: 

    subdir1/* 
    subdir2/* 

水珠*將在subdir小號字母順序排序文件。爲了避免排序，您可以指定訂單，而不是通過匹配。

.. toctree:: 
    :maxdepth: 2 

    subdir1/file2 
    subdir1/file1 
    subdir2/file1 
    subdir2/file2 

如果你不想單獨的網頁，但一個巨大的頁面，你可以調用make singlehtml。