You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
π sphinx-codelinks: three [codelinks] reader policies to settle β unknown keys (both readers), a TOML-set config_from_toml, the schema error channelΒ #2007
Three reader-policy questions that #2005 (sphinx-codelinks reads ubproject.toml through ub-project) measured and deliberately left as they were, because each is a behaviour decision of its own. One issue so they are decided together; they share the [codelinks] reader.
1. Unknown keys inside [codelinks]: the two readers disagree. The Sphinx extension skips a key it does not model silently (set_config_to_sphinx's allow-list); codelinks analyse refuses the same file (CodeLinksConfig.__init__() got an unexpected keyword argument 'bogus_key', rc 2). Under projects.<name> it is the other way round: the extension's jsonschema refuses an unknown key (additionalProperties: False), the CLI ignores it. sphinx-mounts and sphinx-test-reports both WARN with a typed, suppressible subtype (mounts.unknown_key, test_reports.unknown_key); sphinx-needs skips silently. Proposal: both codelinks readers warn (codelinks.config, the subtype #2005 introduced), never refuse β a key several tool versions read at once is the case the shared file exists for. Measured cost: the docs' own docs/ubproject.toml carries no unknown key, so docs-codelinks -nW is unaffected.
2. config_from_toml is a key the TOML itself may set. It is in CodeLinksConfig.field_names(), so [codelinks] config_from_toml = "sub/x.toml" rewrites src_trace_config_from_toml after the load β which moves the use-site anchor (confdir / Path(config_from_toml).parent) to confdir/sub WITHOUT reading sub/x.toml. A file naming its own path is meaningless; the observable effect is a silently moved anchor. Proposal: the reader skips config_from_toml (and the docs say the key is conf.py / -D only). #2005 pinned today's behaviour with a test (test_toml_set_config_from_toml_moves_the_anchor in tests/test_src_trace.py) so this change flips a fenced thing.
3. check_sphinx_configuration reports a schema error as a bare raise Exception, which Sphinx renders as an ExtensionError with its crash-report banner ("please open an issue at sphinx-docβ¦") for what is a user configuration error (set_local_url = "yes"; an unknown key under a project). A sphinx.errors.ConfigError (or ExtensionError raised with a clean message) is the small fix; the message also says "in filed 'set_local_url'" (config.py, check_schema).
All three measured on master at d0edd0e9 by the #2005 recon (sphinx-build -E -q -b html and codelinks analyse over constructed files); none changed by #2005.
Activity