Skip to content

emit a warning when :directory: / :file: filter matches zero traced files #87

Description

@arnoox

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

  1. Configure a project with sphinx-codelinks and at least one .. src-trace:: directive that uses :directory:.
  2. Rename the source folder so the :directory: string no longer matches any traced path.
  3. Run sphinx-build.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions