<p>只是为了记录:我对几个解决方案进行了基准测试。在</p>
<p>我在我的<code>conf.py</code>中创建了一个名为<code>touch_files</code>的函数。它会搜索文件中的字符串,如果找到,则会触发重新生成的文件:</p>
<pre><code>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::')
</code></pre>
<p><code>touch_files</code>可以使用可变数量的参数调用,并在找到其中一个参数时编辑文件。我试图用正则表达式优化函数,但这并没有取得太大的效果。用<code>mmap</code>直接从磁盘读取文件内容似乎影响不大。在</p>
<p>这是78个文件的结果,其中36个文件包含两个指令中的一个。在</p>
^{pr2}$
<p><strong>结果</strong>:每个命令只被调用了几次(除了“touch_files”),因此缺乏统计可靠性。在不检查Sphinx 3.2文档的情况下,大约需要几秒钟的时间来检查Sphinx。一个干净的构建需要13.3秒,这比使用<code>sphinx-build -a</code>的构建要长得多。如果我们只是重建了78个文件中的36个,那么构建过程会稍微快一些,尽管我怀疑这里是否存在显著的差异。“触摸文件”的开销相当低。与编辑时间戳相比,查找字符串相当便宜。在</p>
<p>结论:正如<a href="https://stackoverflow.com/a/44758406/1617563">Steve Piercy</a>指出的,使用<code>sphinx-build -a</code>似乎是最合理的方法。至少对我的用例来说。如果一个不包含有问题的指令的文件会导致较长的生成时间,<code>touch_files</code>可能会有用。在</p>