Summary
When a .. src-trace:: directive is given a :directory: or :file: filter that matches no entries in the codelinks trace JSON, the directive silently renders nothing. No Sphinx warning, no error, no "no results found" message is emitted. This makes stale filter strings (e.g. after a folder rename) completely invisible to the developer.
Current behaviour
.. src-trace::
:project: services
:directory: hil-testing/executors/simulator ← folder was renamed
- HTML output: empty (no content rendered).
sphinx-build output: no warning or error.
- ubCode Problems panel: no diagnostic.
Expected behaviour
When the resolved result set for a :directory: or :file: filter is empty, sphinx-codelinks should call self.state.document.reporter.warning(...) (or equivalent Sphinx logger.warning) with a message such as:
[src-trace] No traced files matched filter directory='hil-testing/executors/simulator'
in project 'services'. Check that the path matches entries in the codelinks output JSON.
This warning should:
- Appear in
sphinx-build -W runs (turning warnings into errors in CI).
- Appear in the ubCode Problems panel.
- Cover both
:directory: and :file: filter options.
Steps to reproduce
- Configure a project with
sphinx-codelinks and at least one .. src-trace:: directive that uses :directory:.
- Rename the source folder so the
:directory: string no longer matches any traced path.
- Run
sphinx-build.
- Observe: output is silently empty, no warning is emitted.
Impact / customer reference
Reported by a Denso team using codelinks in a large Bazel monorepo. A folder rename went unnoticed for an entire sprint because the directive silently dropped all output.
Summary
When a
.. src-trace::directive is given a:directory:or:file:filter that matches no entries in the codelinks trace JSON, the directive silently renders nothing. No Sphinx warning, no error, no "no results found" message is emitted. This makes stale filter strings (e.g. after a folder rename) completely invisible to the developer.Current behaviour
sphinx-buildoutput: no warning or error.Expected behaviour
When the resolved result set for a
:directory:or:file:filter is empty,sphinx-codelinksshould callself.state.document.reporter.warning(...)(or equivalent Sphinxlogger.warning) with a message such as:This warning should:
sphinx-build -Wruns (turning warnings into errors in CI).:directory:and:file:filter options.Steps to reproduce
sphinx-codelinksand at least one.. src-trace::directive that uses:directory:.:directory:string no longer matches any traced path.sphinx-build.Impact / customer reference
Reported by a Denso team using codelinks in a large Bazel monorepo. A folder rename went unnoticed for an entire sprint because the directive silently dropped all output.