始终重新生成包含特定指令的狮身人面像文件

狮身人面像通常会增量生成文档，这意味着只有已更改的文件才会重新生成。我想知道是否有办法告诉狮身人面像总是重新生成某些文件，这些文件可能并未直接更改，但会受到其他文件更改的影响。更具体一点：有没有办法告诉Sphinx总是重新生成包含某个指令的文件？我正在处理的文档依赖于通过指令相当频繁地从其他页面收集和重新格式化信息的可能性。干净（make clean && make [html]）和/或完整（sphinx-build -a）构建比增量构建花费的时间要长得多。此外，手动跟踪包含该指令的文件可能会很复杂。该文档由10多位撰写Sphinx文档的经验不足的作者撰写。始终重新生成包含特定指令的狮身人面像文件

但即使是在不太复杂的情况下，您可能会面对这个“问题”：例如sphinx.ext.todo含有一种叫todolist指令，它收集待办事项从整个文档。如果我从我的文档（基本上只包含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的

内容：中todos.rst

Welcome to sphinx-todo's documentation! 
======================================= 

.. toctree:: 
    :maxdepth: 2 

    todos 


.. todo:: 
I have to do this 


Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search`

内容：

.. _`todos`: 

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

.. todolist::

假设你使用html输出，你会发现，当你添加待办事项到index.htmltodos.html不会改变。

TL;博士：如何 - 如果可能的话 - 我包括含有特定指令（例如todolist）为增量构建狮身人面像，而无需手动跟踪他们的文件？

来源

2017-06-26 aleneum

默认情况下，Sphinx只会更新新文件或更改文件的输出。这是埋在sphinx-build -a。

在命令选项文件的结尾sphinx-build：

你也可以给在命令行中的一个或多个文件名的来源后，并建立目录。然后Sphinx将尝试构建仅这些输出文件（及其依赖项）。

您可以直接或通过makefile调用sphinx-build，具体取决于Sphinx版本随附的生成文件（您也可以自定义生成文件）。

来源

2017-06-26 11:12:04

谢谢你的回答。您的回答支持我目前的印象，即您必须创建所有内容或直接指定要重建的文件。我希望为指令/文件或一些最佳实践预处理（例如before-build-hook）提供一个整洁的隐藏的“白名单”关键字，但似乎并不存在。 – aleneum

只是为了记录：我基准了几个解决方案。

我在我的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个文件包含两个指令之一。

Command         Time  Comment 
time make html       2.3 s No changes 
time sh -c 'make clean && make html' 13.3 s 
time make htmlfull      9.4 s sphinx-build -a  
time make html       8.4 s with 'touch_files' 
'touch_files'       0.2 s tested with testit

结果：每个命令都被称为短短的时间（除了“touch_files”），因此缺乏统计的可靠性。狮身人面像需要大约2.3秒的时间来检查文件的变化而不做任何事情。一个干净的构建需要13.3秒，比sphinx-build -a的构建要长得多。如果我们只重建了78个文件中的36个，构建过程稍微快一点，但我怀疑这里可以找到显着差异。 'touch_files'的开销很小。与编辑时间戳相比，查找字符串相当便宜。

结论：由于Steve Piercy指出，使用sphinx-build -a似乎是最合理的方法。至少在我的用例中。如果一个不包含指令的文件导致建设时间过长，那么touch_files可能会很有用。

来源

2017-06-27 09:37:37 aleneum

始终重新生成包含特定指令的狮身人面像文件

回答

相关问题