Why is toctree not updating with RTD theme?

Question

I have an programmatically generated sphinx-doc source that uses the Read-The-Docs theme. The source tree looks like:

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 includes a TOC like:

.. toctree::
    :maxdepth: 2

    model_search

    ...

and model_search.rst includes all of the model index.rsts:

.. toctree::
    :maxdepth: 1

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

    ...

When I initially build the source with make html, it builds nicely, and creates a TOC that includes all of the existing models.

However, when I add a new model (e.g. 3lin), and then make build again, the TOC is not regenerated on the pages for the existing models (1lin, 2lin, etc). The only way I've found to correctly re-create the TOC on all pages is to either modify the conf.py (e.g. enable/disable autodoc), or to manually touch all of the relevant .rst files.

Should the TOC be regenerating on the old model pages, or is this expected behaviour? If it should be happening, what is going wrong?

Answer 1

It's expected behavior. Sphinx builds only files that have not changed since the last build. You can touch each file, or you can run make clean before running make html.