包括多个带有Sphinx和指令的RST文件。包括：： [英] Include multiple RST files with Sphinx with directive .. include::

问题描述

在我的Sphinx项目中，我希望有一个包含多个RST文件的包含文件夹，以便在其他项目中重复使用。我的源文件夹类似于：

source
    include
         links.rst  # Here I have useful external links
         roles.rst  # Here I define custom roles
         subs.rst   # Here I definne common substitutions (replace directive)
    ... rest of my stuff
    conf.py

基本上，我希望能够在我的源RST文件中编写一个.. include::来说明我的所有文件，即等同于/include/*.rst

我已经想出了一个简洁的解决方案，我在下面发布，因为它可能对其他人有用。但是，听到其他替代方案会很好，因为我的解决方案在使用sphinx-autobuild时会出现无限循环的问题。

推荐答案

我的解决方案包括修改conf.py以包含这一小段代码：

conf.py

import os

# Code to generate include.rst
files = os.listdir('include')

with open('include.rst', 'w') as file:
    for rst in files:
        file.write('.. include:: /include/' + rst + '
')

这将在根源代码目录中创建一个新的include.rst文件，该文件将如下所示：

source
    include
         links.rst  # Here I have useful external links
         roles.rst  # Here I define custom roles
         subs.rst   # Here I definne common substitutions (replace directive)
    ... rest of my stuff
    conf.py
    include.rst

新文件include.rst如下所示：

.. include:: /include/links.rst
.. include:: /include/roles.rst
.. include:: /include/subs.rst

最后，在我的源文件中，我只需要在文件顶部添加行

.. include:: include.rst

受益于我的所有自定义链接、角色和替换(或您可能需要的任何其他内容)。

问题： 我在这里的解决方案提出了一个问题。由于我使用sphinx-autobuild在检测到更改时自动构建html输出，因此会产生无限循环，因为每次conf.py的执行都会创建文件include.rst。有什么办法解决这个问题吗？

更新： 我已经找到了上面提到的问题的解决方案，实际上，这是相当明显的。 现在，我使用--re-ignore选项执行sphinx-autobuild：

> sphinx-autobuild source build/html --re-ignore include.rst

并且循环停止发生。 现在，如果我更改子rst文件(即角色、链接或subs)，这是可以的，但如果include.rst更改(例如，添加了新的子rst文件)，则我需要停止并重新运行sphinx-autobuild。

这篇关于包括多个带有Sphinx和指令的RST文件。包括：：的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！