3di | Enhance metadata

.github/workflows/enhance.yml

@@ -0,0 +1,93 @@
+name: Enhance
+
+# pull_request_target grants GITHUB_TOKEN write access on fork PRs.
+# PR code is checked out as data only; scripts run from the trusted base checkout.
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  ensure-enhancements:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout PR code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          fetch-depth: 0
+
+      - name: Checkout trusted base scripts
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: .trusted-base
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install PyYAML
+        run: pip install --no-warn-script-location pyyaml
+
+      - name: Ensure documentation enhancements
+        id: ensure
+        continue-on-error: true
+        env:
+          DIFF_BASE: ${{ github.event.pull_request.base.sha }}
+        run: |
+          set -euo pipefail
+          git fetch origin "$DIFF_BASE"
+          make -f .trusted-base/Makefile ensure-enhancements \
+            TOOLS_DIR=.trusted-base/tools \
+            DIFF_BASE="$DIFF_BASE" \
+            STATUS_FILE="$GITHUB_OUTPUT"
+
+      # The ensure step soft-fails whenever enhancements are missing, so an empty
+      # enhancements_checked is the only signal that the check itself never ran.
+      - name: Verify enhancement check ran
+        if: steps.ensure.outputs.enhancements_checked == ''
+        run: |
+          echo "The enhancement check produced no outputs; see the ensure step log."
+          exit 1
+
+      - name: Supersede stale enhancement reviews
+        if: steps.ensure.outputs.enhancements_checked == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          make -f .trusted-base/Makefile supersede-enhancement-reviews \
+            TOOLS_DIR=.trusted-base/tools
+
+      # Posts the summary so the Conversation view has a current review after
+      # the stale ones are minimised.
+      - name: Post enhancement review comment
+        if: >-
+          ${{ !cancelled()
+          && steps.ensure.outputs.has_results == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REVIEW_COMMENT: ${{ steps.ensure.outputs.comment }}
+        run: |
+          set -euo pipefail
+          gh pr review "$PR_NUMBER" \
+            --comment \
+            --body "$REVIEW_COMMENT"
+
+      - name: Enforce required enhancements
+        if: always() && steps.ensure.outputs.has_errors == 'true'
+        run: |
+          echo "Required enhancements (error level) are still missing."
+          exit 1

Makefile

@@ -7,6 +7,7 @@ PYTHON := python3
 ifeq ($(OS),Windows_NT)
     PYTHON := python
 endif
+BASH := bash
 BUILD      = $(PYTHON) -m sphinx
 JOBS       ?= auto
 # Attached form (-j<JOBS>, no space) so sphinx-multiversion forwards it to sphinx-build
@@ -15,6 +16,12 @@ OPTS       =-c . -W -j$(JOBS) # Treat warnings as errors, build in parallel ($(J
 LIVE_HOST  ?= 0.0.0.0
 LIVE_PORT  ?= 2022
 
+TOOLS_DIR     ?= tools
+DIFF_BASE     ?=
+STATUS_FILE   ?=
+PR_NUMBER     ?=
+REPOSITORY    ?=
+
 DICTIONARIES := codespell_dictionary.txt codespell_whitelist.txt
 
 help:
@@ -36,11 +43,32 @@ test:
 	doc8 --ignore D001  --ignore-path $(OUT) -- $(SOURCE)
 
 test-tools:
-	$(PYTHON) -m pytest test/
+	$(PYTHON) -m pytest test/ tools/tests/
 
 spellcheck:
 	git ls-files '*.md' '*.rst' | xargs codespell --config codespell.cfg
 
+ensure-enhancements:
+ifndef DIFF_BASE
+	$(error DIFF_BASE is required)
+endif
+ifndef STATUS_FILE
+	$(error STATUS_FILE is required)
+endif
+	$(PYTHON) $(TOOLS_DIR)/ensure_enhancements.py \
+	  --config $(TOOLS_DIR)/enhance.yaml \
+	  --diff-base $(DIFF_BASE) \
+	  --status-file $(STATUS_FILE)
+
+supersede-enhancement-reviews:
+ifndef PR_NUMBER
+	$(error PR_NUMBER is required)
+endif
+ifndef REPOSITORY
+	$(error REPOSITORY is required)
+endif
+	$(BASH) $(TOOLS_DIR)/supersede_enhancement_reviews.sh
+
 check-dictionaries:
 	@echo "Checking dictionaries..."
 	@for dict in $(DICTIONARIES); do \
@@ -69,4 +97,4 @@ linkcheck:
 serve:
 	sphinx-autobuild --host $(LIVE_HOST) --port $(LIVE_PORT) -c . $(SOURCE) $(OUT)/html
 
-.PHONY: help Makefile multiversion test test-tools linkcheck serve lint spellcheck check-dictionaries sort-dictionaries
+.PHONY: help Makefile multiversion test test-tools linkcheck serve lint spellcheck check-dictionaries sort-dictionaries ensure-enhancements supersede-enhancement-reviews $(MAKEFILE_LIST)

conf.py

@@ -90,6 +90,8 @@
     'sphinxcontrib.googleanalytics',
     'sphinxcontrib.mermaid',
     'sphinxext.opengraph',
+    'short_description',
+    'showmeta'
 ]
 
 # Intersphinx mapping
@@ -186,6 +188,7 @@
     'DISTRO_UBUNTU_DEB_PLATFORM': distro_ubuntu_deb_platform['rolling'],
     'DISTRO_ARM_STATUS_SUFFIX': distro_arm_status_suffix.get('rolling', 'unv8'),
     'REPOS_FILE_BRANCH': 'rolling',
+    'PRODUCT': 'ROS 2',
 }
 
 html_favicon = 'favicon.ico'

plugins/meta_util.py

@@ -0,0 +1,70 @@
+# Copyright 2026 Open Robotics — shared helpers for ``.. meta::`` / Pagefind
+"""
+Collect every ``.. meta::`` field from the doctree, sanitize keys, and expand
+``{MACRO}`` placeholders using the Sphinx ``macros`` config (longest keys first).
+
+Sphinx / the HTML theme may also emit plain ``<meta>`` tags for the same fields.
+The Pagefind extension emits additional tags with ``data-pagefind-filter`` and may
+split comma-separated values into multiple tags for faceted search.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional
+
+from docutils import nodes
+
+# HTML ``<meta name="...">`` names should be conservative; allow common patterns.
+_META_NAME_RE = re.compile(r'^[A-Za-z0-9_.:-]+$')
+
+
+def sanitize_meta_key(raw: str) -> Optional[str]:
+    s = str(raw).strip()
+    if not s or not _META_NAME_RE.match(s):
+        return None
+    return s
+
+
+def all_doctree_meta(doctree: Optional[nodes.document]) -> Dict[str, str]:
+    """Return last-wins mapping of every ``nodes.meta`` ``name``/``property`` → ``content``."""
+    if doctree is None:
+        return {}
+
+    out: Dict[str, str] = {}
+    for meta in doctree.findall(nodes.meta):
+        if meta.get('http-equiv'):
+            continue
+        content = meta.get('content')
+        if not content:
+            continue
+        key: Optional[str] = None
+        name = meta.get('name')
+        if name:
+            key = sanitize_meta_key(str(name))
+        else:
+            prop = meta.get('property')
+            if prop:
+                key = sanitize_meta_key(str(prop))
+        if not key:
+            continue
+        out[key] = str(content).strip()
+    return out
+
+
+def expand_meta_macros(text: str, macros: Dict[str, str]) -> str:
+    """Expand ``{KEY}`` placeholders; longer macro names first to avoid partial matches."""
+    result = text
+    for key, value in sorted(macros.items(), key=lambda kv: len(kv[0]), reverse=True):
+        result = result.replace(f'{{{key}}}', value)
+    return result
+
+
+def expand_all_meta_values(meta: Dict[str, str], macros: Dict[str, str]) -> Dict[str, str]:
+    """Apply ``expand_meta_macros`` to every meta value."""
+    return {k: expand_meta_macros(v, macros) for k, v in meta.items()}
+
+
+def split_meta_values(value: str) -> List[str]:
+    """Return comma-separated metadata values as individual Pagefind values."""
+    return [part.strip() for part in value.split(',') if part.strip()]

plugins/short_description.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+
+class ShortDescriptionDirective(SphinxDirective):
+    """Directive to render the short description of an article."""
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    option_spec = {}
+
+    def run(self) -> list[nodes.Node]:
+        # Create a container node to hold the parsed content
+        node = nodes.container()
+        node['classes'].append('short-description')
+
+        # Parse the directive content into the container node
+        self.state.nested_parse(self.content, self.content_offset, node)
+
+        return [node]
+
+
+def setup(app):
+    app.add_directive('short-description', ShortDescriptionDirective)
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+        'version': '0.1.0',
+    }

plugins/showmeta.py

@@ -0,0 +1,120 @@
+# Copyright 2026 Open Robotics — explicit in-body ``.. showmeta::`` summary
+"""
+Render selected ``.. meta::`` fields in the document body with author-controlled
+order and labels. Place ``.. showmeta::`` where the summary should appear (HTML only).
+"""
+
+from __future__ import annotations
+
+import html as html_module
+import re
+from typing import List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.util.docutils import SphinxDirective
+
+from .meta_util import all_doctree_meta, expand_all_meta_values
+
+
+def _macros_flat(app) -> dict[str, str]:
+    return {str(k): str(v) for k, v in (getattr(app.config, 'macros', {}) or {}).items()}
+
+
+def _default_showmeta_label(key: str) -> str:
+    spaced = re.sub(r'([a-z])([A-Z])', r'\1 \2', key)
+    return spaced.replace('_', ' ').replace('-', ' ').strip().title()
+
+
+class showmeta_node(nodes.General, nodes.Element):
+    """Placeholder replaced on ``doctree-resolved`` (HTML builds only)."""
+
+
+class ShowMetaDirective(SphinxDirective):
+    """Insert a visible metadata line built from ``.. meta::`` on this page."""
+
+    has_content = False
+    option_spec = {
+        'order': directives.unchanged,
+        'labels': directives.unchanged,
+    }
+
+    def run(self) -> List[nodes.Node]:
+        node = showmeta_node()
+        node['order'] = self.options.get('order', '')
+        node['labels'] = self.options.get('labels', '')
+        self.set_source_info(node)
+        return [node]
+
+
+def visit_skip_showmeta(self, node: showmeta_node) -> None:
+    raise nodes.SkipNode
+
+
+def depart_showmeta_noop(self, node: showmeta_node) -> None:
+    pass
+
+
+def _parse_labels(raw: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for part in [p.strip() for p in raw.split(',') if p.strip() and '=' in p]:
+        key, _, value = part.partition('=')
+        key, value = key.strip(), value.strip()
+        if key:
+            out[key] = value
+    return out
+
+
+def replace_showmeta_nodes(app, doctree: nodes.document, docname: str) -> None:
+    if app.builder.format != 'html':
+        for node in list(doctree.findall(showmeta_node)):
+            node.parent.remove(node)
+        return
+
+    macros = _macros_flat(app)
+    meta = expand_all_meta_values(all_doctree_meta(doctree), macros)
+
+    for node in list(doctree.findall(showmeta_node)):
+        order = [x.strip() for x in node.get('order', '').split(',') if x.strip()]
+        labels_map = _parse_labels(node.get('labels', ''))
+        if not order:
+            node.parent.remove(node)
+            continue
+
+        parts: List[str] = []
+        for key in order:
+            val = meta.get(key, '').strip()
+            if not val:
+                continue
+            label_base = labels_map.get(key) or _default_showmeta_label(key)
+            label_display = label_base if label_base.rstrip().endswith(':') else f'{label_base}:'
+            parts.append(
+                f'<strong>{html_module.escape(label_display)}</strong> '
+                f'{html_module.escape(val)}'
+            )
+
+        if not parts:
+            node.parent.remove(node)
+        else:
+            inner = ' | '.join(parts)
+            raw = nodes.raw(
+                '',
+                f'<p class="ros-page-meta-summary" data-pagefind-ignore="all">{inner}</p>',
+                format='html',
+            )
+            node.replace_self(raw)
+
+
+def setup(app):
+    app.add_node(
+        showmeta_node,
+        html=(visit_skip_showmeta, depart_showmeta_noop),
+        latex=(visit_skip_showmeta, depart_showmeta_noop),
+    )
+    app.add_directive('showmeta', ShowMetaDirective)
+    app.connect('doctree-resolved', replace_showmeta_nodes)
+    return {
+        'version': '1.0.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }