👌 Honor -D overrides when loading needs_from_toml (#1717)

Keep Sphinx CLI config overrides (`-D` / `confoverrides`) authoritative
in `load_config_from_toml` by skipping TOML assignments for keys that
were already overridden.

- Read override keys from `config.overrides`
- Skip setting `needs_<key>` when `<key>` or `needs_<key>` is overridden
- Skip setting schema entries when `needs_schema_` or
`needs_schema_<key>` is overridden
- Add regression test verifying TOML does not overwrite
`needs_reproducible_json` when provided via `confoverrides`

This preserves expected precedence: CLI overrides > TOML values >
defaults.

Author: chrisjsewell

sphinx_needs/needs.py

@@ -482,17 +482,28 @@ def load_config_from_toml(app: Sphinx, config: Config) -> None:
         return
 
     allowed_keys = NeedsSphinxConfig.field_names()
+    overridden_keys: set[str] = set()
+    config_overrides = getattr(config, "overrides", None)
+    if isinstance(config_overrides, dict):
+        overridden_keys = {str(key) for key in config_overrides}
 
     for key, value in toml_data.items():
         if key not in allowed_keys:
             continue
-        config["needs_" + key] = NeedsSphinxConfig.convert_field_value(
+        config_key = "needs_" + key
+        # Keep values passed via sphinx-build -D (confoverrides) untouched.
+        if key in overridden_keys or config_key in overridden_keys:
+            continue
+        config[config_key] = NeedsSphinxConfig.convert_field_value(
             key, value, toml_file.parent
         )
 
+    schema_config_overridden = "needs_schema_" in overridden_keys
     for key, value in toml_data.get("schema", {}).items():
         if key not in allowed_keys:
             continue
+        if schema_config_overridden or f"needs_schema_{key}" in overridden_keys:
+            continue
         config["needs_schema_"][key] = NeedsSphinxConfig.convert_field_value(
             key, value, toml_file.parent, "schema_"
         )

tests/test_needs_from_toml.py

@@ -24,3 +24,22 @@ def test_needs_from_toml(test_app, snapshot):
     assert data == snapshot(
         exclude=props("created", "project", "creator", "needs_schema")
     )
+
+
+@pytest.mark.parametrize(
+    "test_app",
+    [
+        {
+            "buildername": "html",
+            "srcdir": "doc_test/needs_from_toml",
+            "no_plantuml": True,
+            "confoverrides": {"needs_reproducible_json": False},
+        }
+    ],
+    indirect=True,
+)
+def test_needs_from_toml_respects_overrides(test_app):
+    app = test_app
+    app.build()
+    assert not app._warning.getvalue()
+    assert app.config.needs_reproducible_json is False