3di | Enhance metadata

[keithkirkwood-3di]

Description

This PR introduces the mechanism and configuration for automated RST documentation enhancement checks required to support the new ROS documentation information architecture. All RST files created or modified in a pull request to the default branch (rolling) on ros2_documentation are checked against rules defined in tools/enhance.yaml:

Document metadata

• Ensures configured metadata fields are present at the top of the file.
• Rules may specify suggested default values (such as Sphinx build macros {PRODUCT} and {DISTRO}) or require the contributor to supply a non-empty value (e.g. area).

Post-heading directives

• .. short-description:: Checks that the first prose paragraph after the primary document title is wrapped in a .. short-description:: directive.
• .. showmeta:: Checks that a .. showmeta:: directive exists after the title area with the configured options (e.g. :order: area, content-type, experience).
• Each rule can be configured as a warning (advisory; the ensure step soft-fails but the workflow succeeds) or an error (blocking; the workflow fails after feedback is posted).

Pull request feedback

When enhancements are missing, the Enhance workflow posts a single Documentation enhancements summary review comment on the pull request. For each affected file, the comment lists:

• Missing .. meta:: fields (labelled required or optional, with suggested values where configured), and
• Missing after-title directives (with brief guidance on what to add).

The tool is read-only: it does not modify RST files, emit inline commit suggestions, or post check annotations.

On subsequent workflow runs in the same PR, stale summary reviews are automatically minimised as Outdated and replaced with an updated summary if enhancements are still missing. When all issues are resolved, outdated reviews are cleared and no new comment is posted.

Testing

For security reasons, the new Enhance workflow runs trusted code from the base branch of the PR (typically rolling), while processing content from the incoming head branch. This pattern (using pull_request_target in GitHub Actions) grants necessary write permissions for fork PRs (enabling inline suggestions and review comments) without executing untrusted code from forks.

To test this PR locally or on a fork:

1. Fork this repository.
2. Merge these PR changes into the default branch (rolling) of your fork first.
3. Open a test PR against your fork targeting rolling with new or edited .rst files.

Changes

• Add tools/enhance.yaml configuration for meta field rules and after_title directive rules (.. short-description::, .. showmeta::), with per-rule warning / error severity and suggested default values where applicable.
• Add tools/enhance_config.py to load and validate enhancement rules from YAML.
• Add tools/ensure_enhancements.py CLI to check changed RST files against the config, generate Documentation enhancements summary review comments, and emit GitHub Actions status outputs for CI. The tool is read-only and does not modify source files.
• Add tools/rst_utils.py read-only helpers to detect .. meta:: fields and the presence of .. short-description:: / .. showmeta:: directives.
• Add tools/supersede_enhancement_reviews.sh to minimise outdated summary review comments via the GitHub GraphQL API.
• Add .github/workflows/enhance.yml workflow to run enhancement checks on pull requests, supersede stale reviews, post summary review comments, and fail the job when error-severity rules are unmet.
• Update Makefile with ensure-enhancements and supersede-enhancement-reviews targets, and extend test-tools to run the tools/tests/ unit suite (via PYTHONPATH).
• Add unit test suites in tools/tests/test_ensure_enhancements.py and tools/tests/test_rst_utils.py.
• Update documentation in tools/README.md.
• Add {PRODUCT} and {DISTRO} macro placeholders expanded by Sphinx in conf.py.

Did you use Generative AI?

Yes - Cursor IDE, using models Composer 2.5, Gemini Pro 3.1, Flash 3.6, and Anthropic Sonnet 5 / Opus 5.

Additional Information

Issue: #6991