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

Question

In my Sphinx project, I want to have a include folder with multiple RST files that I can reuse in other projects. My source folder looks something like:

\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

Basically, I want to be able to write a single .. include:: in my source RST files that will account for all my files, ie the equivalent of /include/*.rst

I have come up with a neat solution that I post below since it might be usefult to someone else. However, it would be nice to hear other alternatives, since my solution comes with a problem of infinite loop when using sphinx-autobuild .

Answer 1

My solution consists of modifying conf.py to include this small piece of code:

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')

This will create a new include.rst file in the root source directory, which will look as:

\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

With the new file include.rst looking like:

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

Finally, in my source files I only need to add on top of the file the line

.. include:: include.rst

to benefit from all my custom links, roles, and substitutions (or anything else you might want there).

PROBLEM: My solution here presents a problem. Since I use sphinx-autobuild to automatically build the html output whenever a change is detected, an infinite loop is produced, since each time the execution of conf.py is creating the file include.rst . Any ideas on how to solve this?

UPDATE: I have found the solution to the problem mentioned above, and which was pretty obvious, actually. Now I execute sphinx-autobuild with the --re-ignore option as:

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

and the loop stops happening. Now, this is OK if I change the children rst files (ie roles, links, or subs) but if the very include.rst changes (eg a new children rst file was added) then I need to stop and re-run sphinx-autobuild .