PoC feature_in_id for single module repositories

[MaximilianSoerenPollak]

📌 Description

This is a suggestion/PoC on how we could allow for the feature_in_id check to be kept but adapt it so that single feature /module repositories also pass this check.
This is done here by adding an additional config parameter to the conf.py that defines strings that are also allowed in the feature_part of the id.
Now only if NONE of the 3 things (docpath, abbreviation or configured param) are found an error is thrown.

Fixes #596

🚨 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: 011b156f-6ee8-4098-9627-132fdafd2c8e
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.845s
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):

The match is against the full need ID (e.g. feat_req__blabla__testing) rather than the feature part alone (parts[1]). This means a config entry like "feat" or "req" would silently suppress the check for every 3-part ID, regardless of the actual feature value.

The check should compare against feature (i.e. parts[1]) to match the documented intent: "strings that are also allowed in the feature_part of the id".

Suggested change

	for part_from_config in allowed_parts_from_config
	found_part_from_config = any(
	part_from_config.lower() in feature.lower()
	for part_from_config in allowed_parts_from_config
	if allowed_parts_from_config
	)

[AlexanderLanin]

AI-assisted review (Claude):

Adding required_in_id = ["blabla"] to the shared conf.py affects every test that uses this Sphinx build, not just the new id_contains_feature tests. Any test whose need ID happens to contain the string "blabla" would silently bypass the id_contains_feature check.

More importantly, this is a globally-permissive sentinel value chosen purely for testing. When reviewing or debugging failures, it's non-obvious why blabla is allowed globally. A more precise approach: add a dedicated conf.py under the id_contains_feature/ subdirectory so test isolation is explicit.

[MaximilianSoerenPollak]

This is a non issue as we only tests single checks in each RST file.
This will not interfeer.

[AlexanderLanin]

AI-assisted review (Claude):

"persistenc" is a partial string that would match persistence, persistency, etc. If this substring match is intentional, it should be explained in the docs — readers will assume it's a typo for "persistence" and either copy it incorrectly or fix it in their own conf.py without understanding why the truncation was used.

If the intent is an exact feature name, use the full string. If partial matching is a deliberate affordance, document it explicitly here.

[AlexanderLanin]

AI-assisted review (Claude):

This test verifies that feat_req__blabla__testing does not produce a warning when required_in_id = ["blabla"] is set — good. But there's no test for the negative boundary: a need whose ID contains blabla only in the type or title segment (e.g. feat_req__other__blabla_testing) should still trigger a warning.

Once the match is narrowed to the feature part (see comment on id_contains_feature.py), a test like this is needed to confirm the fix doesn't over-suppress.

[MaximilianSoerenPollak]

Seems plausible. Will add this.

[AlexanderLanin]

AI-assisted review (Claude):

Critical: 0 | Important: 2 | Suggestions: 1

The feature direction is right — a config-driven escape hatch for single-module repos is a reasonable solution to #596. The implementation has two important correctness issues and one suggestion.

Important: config match is against the full ID, not the feature part
Line 63 checks part_from_config.lower() in need.get("id"), which matches the entire ID string (type prefix + feature + title). This means required_in_id = ["feat"] or required_in_id = ["req"] would silently disable the check for every requirement in the build. The match should be against feature (parts[1]) — the documented scope. See inline comment.

Important: required_in_id = ["blabla"] added to the shared test conf.py
This setting applies to all Sphinx test builds under tests/rst/, not just the id_contains_feature tests. Other test files inherit this config and would silently bypass the check for any ID containing blabla. Isolating this behind a per-subdirectory conf.py is cleaner and safer.

Suggestion: docs example uses "persistenc" (truncated string)
The example in write_docs.rst uses a partial string. Since the check does substring matching, this works — but readers will assume it is a typo. Either document that partial strings are intentional, or use the full module name to avoid confusion.