python-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

原则上，这很好用，除了sphinx递归地寻找它试图解析的.rst文件。无需更改当前工作目录。因此，当在include:: file1.rst中看到subdir1时，它将失败。

我正在通过设置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。