为什么 toctree 不更新 RTD 主题？

Question

我有一个以编程方式生成的 sphinx-doc 源，它使用 Read-The-Docs 主题。源树看起来像：

source
├── conf.py
├── index.rst
├── models
│   ├── 1lin
│   │   ├── 1lin_Amplero.rst
│   │   ├── 1lin_Blodgett.rst
│   │   ├── 1lin_Bugac.rst
│   │   ├── ..
│   │   ├── figures
│   │   │   ├── 1lin_all_PLUMBER_plot_all_metrics.png
│   │   │   ├── 1lin_all_PLUMBER_plot_distribution_metrics.png
│   │   │   ├── 1lin_all_PLUMBER_plot_standard_metrics.png
│   │   │   ├── Amplero
│   │   │   │   ├── 1lin_Amplero_PLUMBER_plot_all_metrics.png
│   │   │   │   ├── 1lin_Amplero_rank_counts_all_metrics.png
│   │   │   ..  .. 
│   │   ├── index.rst
│   │   .. 
│   ├── 2lin
│   │   ├── 2lin_Amplero.rst
│   │   ├── 2lin_Blodgett.rst
│   │   ├── 2lin_Bugac.rst
│   │   │   ..  
│   │   ├── index.rst
│   │   .. 
├── model_search.rst
├── sphinx_static
│   ├── jquery
│   │   ├── AUTHORS.txt
│   ..  ..
├── sphinx_templates
│   └── layout.html
..

index.rst 包含如下目录：

.. toctree::
    :maxdepth: 2

    model_search

    ...

和model_search.rst包括所有模型index.rsts:

.. toctree::
    :maxdepth: 1

    models/1lin/index
    models/2lin/index

    ...

当我最初使用 make html 构建源代码时，它构建得很好，并创建了一个包含所有现有模型的目录。

但是，当我添加新模型（例如 3lin），然后再次 make build 时，TOC 不会在现有模型的页面上重新生成（1lin， 2lin，等等）。我发现在所有页面上正确重新创建目录的唯一方法是修改 conf.py（例如 enable/disable autodoc），或者手动 touch 所有相关 .rst 个文件。

TOC 应该在旧模型页面上重新生成，还是这是预期的行为？如果它应该发生，出了什么问题？

Answer 1

这是预期的行为。 Sphinx 仅构建自上次构建以来未更改的文件。可以touch每个文件，也可以运行make clean之前运行宁make html。

为什么 toctree 不更新 RTD 主题？

Why is toctree not updating with RTD theme?

makefile

python-sphinx

read-the-docs

autodoc

toctree