包括多个带有Sphinx和指令的RST文件。包括::

2022-04-22 00:00:00 python python-sphinx

问题描述

在我的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

相关文章