Skip to content

🐛 Don't mutate rebuild='env' src_trace_projects config during builds#75

Merged
ubmarco merged 1 commit into
mainfrom
fix/74-src-trace-projects-incremental-rebuild
Jun 10, 2026
Merged

🐛 Don't mutate rebuild='env' src_trace_projects config during builds#75
ubmarco merged 1 commit into
mainfrom
fix/74-src-trace-projects-incremental-rebuild

Conversation

@ubmarco

@ubmarco ubmarco commented Jun 8, 2026

Copy link
Copy Markdown
Member

Summary

Incremental Sphinx builds always re-read every document, logging
[config changed ('src_trace_projects')] N added, 0 changed, 0 removed, even
when nothing changed — incremental builds behave like full rebuilds.

src_trace_projects is registered with rebuild="env", so Sphinx pickles it
into environment.pickle and invalidates the environment whenever the pickled
("old") value differs from the freshly computed ("new") one.
generate_project_configs() stores runtime analyse_config /
source_discover_config dataclass objects in that value; on their own they
round-trip through pickle as ==-equal.

The bug: the src-trace directive mutated the stored analyse_config in
place
during the build (src_dir, src_files, git_root set to build-time,
resolved values). Those build-time values were persisted into the pickle, while
the next build's config-inited produced a fresh analyse_config
(src_files=[], src_dir=Path(".")), so the comparison always differed:

Side src_dir src_files
persisted (pickle, "old") /abs/.../dcdc ['demo_3.cpp', ...]
fresh config-inited ("new") Path('.') []

Fix

Operate on a per-directive dataclasses.replace() copy instead of mutating the
analyse_config stored in the rebuild="env" config value. The stored value
then stays equal to what generate_project_configs() yields, so incremental
builds report 0 added, 0 changed, 0 removed.

Verification

  • New regression test test_incremental_build_keeps_src_trace_projects_unchanged
    builds the fixture twice and asserts the 2nd (incremental) build sees
    CONFIG_OK — fails before the fix (CONFIG_CHANGED ('src_trace_projects')),
    passes after.
  • Full suite: 207 passed.
  • Manual triple build: builds 2 & 3 now report 0 added, 0 changed, 0 removed.

Fixes #74

The src-trace directive populated src_dir/src_files/git_root directly on the
analyse_config object stored inside src_trace_projects. That value is registered
with rebuild="env", so the build-mutated object was pickled into
environment.pickle; on the next build Sphinx compared it against the freshly
generated (empty) config and reported [config changed ('src_trace_projects')],
forcing a full re-read of all docs on every incremental build.

Work on a per-directive dataclasses.replace() copy so the stored config value
stays equal to what generate_project_configs() yields. Add a regression test
that builds the fixture twice and asserts the second build sees CONFIG_OK.

Refs #74
@ubmarco ubmarco force-pushed the fix/74-src-trace-projects-incremental-rebuild branch from 502c3ee to ef25f45 Compare June 8, 2026 12:19
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.66667% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.86%. Comparing base (c9e78da) to head (ef25f45).

Files with missing lines Patch % Lines
...codelinks/sphinx_extension/directives/src_trace.py 66.66% 1 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main      #75      +/-   ##
==========================================
+ Coverage   90.79%   90.86%   +0.06%     
==========================================
  Files          30       30              
  Lines        2771     2790      +19     
  Branches      305      305              
==========================================
+ Hits         2516     2535      +19     
  Misses        160      160              
  Partials       95       95              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ubmarco ubmarco requested a review from patdhlk June 8, 2026 12:35
@ubmarco ubmarco merged commit d8131d8 into main Jun 10, 2026
13 checks passed
@ubmarco ubmarco deleted the fix/74-src-trace-projects-incremental-rebuild branch June 10, 2026 07:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Incremental builds always re-read all docs: [config changed ('src_trace_projects')]

3 participants