python - 始终重新生成包含特定指令的 Sphinx 文档

Question

Sphinx 通常增量构建文档，这意味着只有已更改的文件才会重新生成。我想知道是否有一种方法可以告诉 Sphinx 始终重新生成某些文件，这些文件可能没有直接更改，但受到其他文件更改的影响。更具体地说:有没有办法告诉 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的内容:

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.rst的内容:

.. _`todos`:

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

.. todolist::

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

tl;dr:如果可能的话，我如何将包含特定指令(例如 todolist)的文件包含到 Sphinx 的增量构建中，而不需要手动跟踪它们？

Answer 1

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

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