始终重新生成包含特定directi的Sphinx文档

Question

Sphinx通常以增量方式构建文档，这意味着只有已更改的文件才会重新生成。我想知道是否有一种方法可以告诉斯芬克斯总是重新生成某些文件，这些文件可能没有直接被更改，但会受到其他文件更改的影响。更具体地说：有没有一种方法可以告诉Sphinx总是重新生成包含某个指令的文件？我正在处理的文档依赖于在指令的帮助下从其他页面收集和重新格式化信息的可能性。一个干净的（make clean && make [html]）和/或完整（sphinx-build -a）生成比增量生成花费的时间要长得多。另外，手动跟踪包含指令的文件可能会很复杂。本文档由10多位在Sphinx文档编写方面经验有限的作者编写。在

但即使在不太复杂的情况下，你也可能面临这样的“问题”： 例如，sphinx.ext.todo包含一个名为todolist的指令，它从整个文档收集todo。如果我创建一个包含文档中所有todo的文件（基本上是一个只包含todolist指令的空文档），则在我进行干净构建或更改文件之前，列表不会更新。在

如果您想自己测试它：用sphinx-quickstart创建一个文档，并坚持使用默认值，除了

'> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y'

在source中添加一个名为todos.rst的文件，并从index.rst引用该文件。在

index.rst的内容：

^{pr2}$

todos.rst的内容：

.. _`todos`:

List of ToDos
=============

.. todolist::

假设您使用html输出，您会注意到当您将todo添加到index.html时，todos.html不会改变。在

太长了，读不下去了，如果有可能的话，我是否需要包含一个特定指令的文件（例如{{CD3>}）到狮身人面像的增量EME>构建，而不需要手动跟踪它们？在

Answer 1

只是为了记录：我对几个解决方案进行了基准测试。在

我在我的conf.py中创建了一个名为touch_files的函数。它会搜索文件中的字符串，如果找到，则会触发重新生成的文件：

def touch_files(*args):
    # recursively search the 'source' directory
    for root, dirnames, filenames in os.walk('.'):
        # check all rst files
        for filename in fnmatch.filter(filenames, '*.rst'):
            cur = os.path.join(root, filename)
            f = open(cur)
            # access content directly from disk
            s = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
            if any(s.find(d) != -1 for d in args):
                # if a string pattern has been found alter the edit 
                # time of the file
                os.utime(cur, None)
            f.close()

# actually call the function
touch_files('.. todolist::')

touch_files可以使用可变数量的参数调用，并在找到其中一个参数时编辑文件。我试图用正则表达式优化函数，但这并没有取得太大的效果。用mmap直接从磁盘读取文件内容似乎影响不大。在

这是78个文件的结果，其中36个文件包含两个指令中的一个。在

^{pr2}$

结果：每个命令只被调用了几次（除了“touch_files”），因此缺乏统计可靠性。在不检查Sphinx 3.2文档的情况下，大约需要几秒钟的时间来检查Sphinx。一个干净的构建需要13.3秒，这比使用sphinx-build -a的构建要长得多。如果我们只是重建了78个文件中的36个，那么构建过程会稍微快一些，尽管我怀疑这里是否存在显著的差异。“触摸文件”的开销相当低。与编辑时间戳相比，查找字符串相当便宜。在

结论：正如Steve Piercy指出的，使用sphinx-build -a似乎是最合理的方法。至少对我的用例来说。如果一个不包含有问题的指令的文件会导致较长的生成时间，touch_files可能会有用。在

Answer 2

默认情况下，Sphinx只更新新文件或更改文件的输出。这是埋在^{}下面的。在

在sphinx-build的命令选项文档末尾：

You can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only these output files (and their dependencies).

您可以直接调用sphinx-build，也可以通过makefile调用，这取决于Sphinx版本附带的makefile（您也可以自定义makefile）。在