如何在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它试图解析的-files.不改变当前工作的目录.因此,当看到include:: file1.rst内部时它失败了subdir1.

我正在解决这个问题,设置exclude_pattern忽略我的子目录.这似乎不对.

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

Answer 1

该toctree指令应该做你想要什么。

.. toctree::
    :glob:

    subdir1/*
    subdir2/*

全局*将按字母顺序对subdirs中的文件进行排序。为避免排序，您可以指定顺序而不会引起混乱。

.. toctree::
    :maxdepth: 2

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

如果您不希望单个页面而是一个大页面，则可以调用make singlehtml。