使用帶有指令的 Sphinx 包含多個 RST 文件.. 包括::

Question

在我的 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時會出現無限循環問題。

Answer 1

我的解決方案包括修改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 + '\n')

這將在根源目錄中創建一個新的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 output 每當檢測到更改時，就會產生無限循環，因為每次執行conf.py都會創建文件include.rst 。 關於如何解決這個問題的任何想法？

更新：我已經找到了上述問題的解決方案，實際上這很明顯。 現在我使用--re-ignore選項執行sphinx-autobuild ：

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

並且循環停止發生。 現在，如果我更改子 rst 文件（即角色、鏈接或子文件），這沒問題，但如果include.rst發生更改（例如添加了新的子 rst 文件），那么我需要停止並重新運行sphinx-autobuild 。