Fix: Update RST File Based Tests

[MaximilianSoerenPollak]

📌 Description

Current RST tests were quite hard to code directly and were error prone without having any insight.
This PR changes the RST tests to make them more explicit as well as making future expandability easier possible

🚨 Impact Analysis

• This change does not violate any tool requirements and is covered by existing tool requirements
• This change does not violate any design decisions
• Otherwise I have created a ticket for new tool qualification

✅ Checklist

• Added/updated documentation for new or changed features
• Added/updated tests to cover the changes
• Followed project coding standards and guidelines

[github-actions]

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: 9c2f1d29-e434-43dd-970a-b335984fc416
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
WARNING: Target pattern parsing failed.
ERROR: Skipping '//src:license-check': no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
ERROR: no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
INFO: Elapsed time: 5.312s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

[github-actions]

The created documentation from the pull request is available at: docu-html

[AlexanderLanin]

AI-assisted review (Claude):

Critical: 0 | Important: 1 | Suggestions: 3

Overall this is a clear improvement: the new #EXPECT[+N] syntax makes test intent explicit, the line-offset validation catches malformed test files before Sphinx runs, and replacing os.chdir with monkeypatch.chdir is the right call for test isolation. The refactoring into extract_test_data + group_test_data is clean.

Important

• Removing the score_metamodel filter on warnings widens the pool to all Sphinx warnings. The position filter protects EXPECT checks, but EXPECT-NOT checks could spuriously fail if Sphinx emits an unrelated warning on the same line as a need. Needs a clear justification (inline comment or PR description). See inline comment on line 295.

Suggestions

• DOCS_DIR and logger are dead code — neither is referenced after this PR. Drop both (line 25, line 32).
• if not rst_data_raw is an unreachable branch — RstData is always truthy and extract_test_data never returns None (line 270).
• Missing space in the offset == 1 error message: "...and need.Please add..." (line 166).
• Commented-out debug print has a syntax error: for w warnings → for w in warnings (line 299).

[MaximilianSoerenPollak]

@AlexanderLanin I in cooperated some of the Review comments, have another look if you can.

[a-zw]

Why is that?

[MaximilianSoerenPollak]

There needs to be a new line between the EXPECT/-NOT and the need.
If that is not the case, then our parser sees it correctly (as we just filter for '.. ' and '::') but sphinx-needs or more precisely docutils thinks it is normal text and doesn't actually generate the need itself.
Therefore we have a miss match of what we see and what sphinx sees. This is not fixable on our side (making the need when sphinx doesn't see it). So we have to enforce (lightly) that there is a new line.

[a-zw]

It seems to practically always be [+2]. So it feels more like unnecessary boilerplate.

[MaximilianSoerenPollak]

That is currently cause we only have 1 EXPECT there. If we had 2 or more it would be `
EXPECT[+3]: ...
EXPECT[+2]: ...

etc.
It truly is only an offset that EXACTLY tells us where they want the warning to be.
This way we can also safeguard a bit against sphinx not seeing a need but we do.

[AlexanderLanin]

AI-assisted review (Claude):

logger is imported and instantiated here but never called anywhere in this file. Dead code — drop both lines.

Suggested change

logger = get_logger(__file__)

[AlexanderLanin]

AI-assisted review (Claude):

Critical: 0 | Important: 0 | Suggestions: 1

---

Good shape. The previous round's concerns are all addressed:

• Dead DOCS_DIR removed ✅
• if not rst_data_raw dead guard removed ✅
• Missing space in the offset-1 error message fixed ✅
• Commented-out debug print syntax error fixed ✅
• Warning filter broadening: the comment on line 302–304 explains the rationale. Acceptable. ✅
• monkeypatch.chdir replacing os.chdir ✅

One small thing remaining: logger (lines 22 + 29) is imported and instantiated but never called. See inline comment.