如何在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。