如何在 sphinx 项目中正确包含其他 ReST 文件？

Question

我的手写 documentation/user-guide（用 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 文件。无需更改当前工作目录。因此，当在 subdir1.

中看到 include:: file1.rst 时失败

我正在通过设置 exclude_pattern 忽略我的子目录来解决这个问题。这好像不太对。

包含子目录的 .rst 文件的正确方法是什么？

Answer 1

toctree directive 应该做你想做的事。

.. toctree::
    :glob:

    subdir1/*
    subdir2/*

glob * 将在 subdir 秒内按字母顺序对文件进行排序。为避免排序，您可以指定不带通配符的顺序。

.. toctree::
    :maxdepth: 2

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

如果您不想要单个页面而是一个大页面，您可以调用 make singlehtml.

How to correctly include other ReST-files in a sphinx-project?