👌 sphinx-codelinks: settle the three [codelinks] reader policies (unknown keys, TOML-set config_from_toml, ConfigError)

[patdhlk]

Fixes #2007: settles the three [codelinks] reader policies that #2005 measured and left alone, following the issue's proposals.

1. Unknown keys: both readers warn, neither refuses

A new drop_unread_keys function in config.py is called by both readers right after load_codelinks_table. It removes:

• unknown [codelinks] keys
• unknown [codelinks.projects.<name>] keys. Only source_discover, analyse and remote_url_pattern are read. The runtime-built source_discover_config / analyse_config count as unknown in a file.

It emits one warning per table that has unknown keys, naming the file, the table, the keys and the supported keys. In Sphinx the warning is codelinks.config, the subtype #2005 introduced, so it can be suppressed. codelinks analyse prints it to stderr and carries on (it used to exit with rc 2).

	before (extension / CLI)	after (both)
[codelinks] bogus_key	silently skipped / rc 2 unexpected keyword argument	warn + skip
[codelinks.projects.p] bogus	build fails (jsonschema) / silently ignored	warn + skip

A project declared in conf.py is still checked strictly by the schema. That file belongs to codelinks alone, so the shared-file argument doesn't apply to it. It now fails as a ConfigError (see 3).

2. config_from_toml inside the TOML is ignored, with a warning

The same filter drops it, so the anchor no longer moves to confdir/<dir of that name>. The pin test test_config_from_toml_set_in_the_toml_moves_the_anchor is flipped to …_is_ignored, and the docs now say the key is conf.py / -D only. I chose to warn rather than skip silently, for the reason item 1 gives: otherwise a key the user wrote would do nothing without any notice.

3. Schema errors are a sphinx.errors.ConfigError

check_sphinx_configuration used to raise a bare Exception, which Sphinx wrapped in an ExtensionError with the crash banner. It now raises a ConfigError with an Invalid sphinx-codelinks configuration: header, which EventManager.emit passes through unchanged. "in filed" is now "in field".

Tests

• test_src_trace.py: unknown top-level and project keys (parametrised over the runtime-only keys too), the flipped config_from_toml test, a suppressibility test, and a ConfigError test for both a TOML type error and an unknown conf.py project key.
• test_cmd.py: codelinks analyse exits 0, warns and writes its output for each of the three cases.

Checks

• uv run poe test-codelinks: 413 passed, 0 skipped
• uv run poe lint: clean
• uv run poe typecheck: clean
• uv run poe docs-codelinks: build succeeded

[read-the-docs-community]

Documentation build overview

📚 sphinx-codelinks | 🛠️ Build #34894662 | 📁 Comparing 66bcf7b against latest (16f247c)

  🔍 Preview build  

3 files changed

± changelog.html
± components/configuration.html
± development/traceability.html