3di | Enhance metadata

[keithkirkwood-3di]

Description

This PR introduces the mechanism and configuration for automated RST docs enhancements required to support the new ROS documentation information architecture. In effect, 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:

1. Document Metadata (.. meta:: block):

   • Ensures standard metadata fields exist at the top of the file.
   • Supports fixed default values (such as Sphinx build macros {PRODUCT} and {DISTRO}) as well as fields that require manual input from contributors (e.g. area).

2. Post-Heading Directives (after_title):

   • .. short-description::: Automatically wraps the first prose paragraph after the primary document title in a .. short-description:: directive. Source sentence formatting (such as "one sentence per line") is preserved with standard 3-space directive indentation.
   • .. showmeta::: Automatically inserts or completes a .. showmeta:: directive immediately following the short description with configured options (e.g. :order: area, content-type, experience).

Each rule can be configured as a warning (advisory, non-blocking step failure) or an error (blocking error that fails the workflow).

Inline Suggestions & Summary Reviews:

• If the changes in an RST file overlap either the top of the file (.. meta::) or the after-title/prose area (short-description / showmeta), GitHub Actions appends inline Commit suggestions on the Files changed tab.
• Annotations anchor to the relevant line: .. meta:: issues anchor to line 1/top-of-file, while after-title issues anchor to the paragraph being wrapped beneath the heading.
• If an edit location does not overlap the diff, the tool generates a structured summary review comment with copy-pasteable RST code blocks or instructions for manual inputs.
• 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.

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

• Rename config to tools/enhance.yaml and add support for after_title directive rules.
• Implement tools/ensure_enhancements.py CLI to enforce metadata fields and wrap/insert after-title directives (.. short-description:: and .. showmeta::).
• Implement tools/rst_utils.py helpers for directive parsing, prose extraction, sentence-line preservation, and directive injection.
• Add tools/supersede_enhancement_reviews.sh script to minimise outdated review comments via GitHub GraphQL API.
• Add PRODUCT and DISTRO macro placeholders expanded by Sphinx in conf.py.
• Add .github/workflows/enhance.yml workflow to orchestrate enhancement checks, inline suggestions (suggest-changes), and summary reviews.
• Update Makefile with ensure-enhancements and supersede-enhancement-reviews targets.
• Add comprehensive unit test suites in tools/tests/test_ensure_enhancements.py and tools/tests/test_rst_utils.py.
• Update documentation in tools/README.md.

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

[keithkirkwood-3di]

Taking this back to draft so I can push more commits for workflow features and test them in-place.

[kscottz]

@keithkirkwood-3di Can you clarify what this is supposed to do exactly? From what I gather this is supposed to add metadata and a short description to a given article. Why isn't it sufficient to just check that that those two directives exist in the file and that there is some text after the directive? Wouldn't it be easier to ask new contributors to include a brief description of the article they just contributed?

[keithkirkwood-3di]

@keithkirkwood-3di Can you clarify what this is supposed to do exactly? From what I gather this is supposed to add metadata and a short description to a given article. Why isn't it sufficient to just check that that those two directives exist in the file and that there is some text after the directive? Wouldn't it be easier to ask new contributors to include a brief description of the article they just contributed?

Hey Kat - yeah, this is correct as far as you go. However, one piece of the metadata (area) is essential for the complete solution we are building for OR, and some is optional (these are reflected in the severities). Also, some of the metadata can have a fixed value (product and distro) and some need to be populated by the contributor.

The short description also needs to be tagged with a new directive, and placed just under the first heading to follow the design our content consultant came up with. In my view, all of this wants to be configurable for future expansion.

In addition, we got guidance from Geoff and Tully that we should use the Suggested changes mechanism here in GitHub where possible, which is what I've done, falling back to a comment with the missing elements only if needed.

When we put all of this together with the design from our tech consultant, you've got the UX and solution described in this PR.

We should of course also update the contribution docs to reflect all this, but the intention here was to create fine-grained validation to support the new IA which 3di is delivering.

[keithkirkwood-3di]

@kscottz Hello - did my reply last week make sense, or do you have any other thoughts on this? There's a README in the /tools directory explaining all this from both user and dev perspectives.

[kscottz]

As it stands this is about 3k lines of code that we're going to need to maintain. I understand that it would be nice to have a "suggest changes" feature that enforces a particular policy, but couldn't we accomplish compliance by largely providing a restructured text template with an example header, a guide for news users, and a simple CI check to make sure the header is included?

[keithkirkwood-3di]

@kscottz Thanks for the feedback - think I'd best discuss this with the rest of the 3di team before going much further. Either myself or someone else on the team will get back to you soon.

[keithkirkwood-3di]

@kscottz Hi Kat - we'll remove all the code concerned with suggested changes and annotations, leaving only the checks for metadata, meta display and short description directives, as these specifically support the information architecture. As you say, we can then have example(s) in the contributor docs for these for use in the header.

I'm pretty sure this will drastically cut down the code present in this PR and give a leaner solution.