ROS project adopter support. (backport #6309)

conf.py

@@ -86,6 +86,7 @@
     'sphinx_tabs.tabs',
     'sphinx_rtd_theme',
     'sphinx_sitemap_ros',
+    'sphinx_adopters',
     'sphinxcontrib.googleanalytics',
     'sphinxcontrib.mermaid',
 ]
@@ -177,7 +178,8 @@
 html_sourcelink_suffix = ''
 
 # Relative to html_static_path
-html_css_files = ['custom.css']
+html_css_files = ['custom.css', 'adopters.css']
+html_js_files = ['adopters.js']
 
 # -- Options for HTMLHelp output ------------------------------------------
 

plugins/adopters_schema.py

@@ -0,0 +1,102 @@
+# Copyright 2026 Sony Group Corporation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Shared schema constants and validation for the ROS 2 adopters YAML file.
+This module has NO Sphinx dependency so it can be used in tests and CI scripts.
+
+NOTE: The domain constants defined here must be kept in sync with
+the corresponding values in source/_static/adopters.js (VALID_DOMAINS).
+Any additions or changes must be applied to both files.
+"""
+
+import re
+
+VALID_DOMAINS = [
+    'Agriculture',         # Farming, harvesting, crop monitoring, and precision agriculture
+    'Aerial/Drone',        # UAVs, drones, aerial inspection, and survey systems
+    'Automotive',          # Self-driving cars, ADAS, and ground vehicle autonomy
+    'Components',          # Robot parts and peripherals (cameras, LIDAR, RADAR, SONAR, etc)
+    'Construction',        # Site inspection, surveying, and construction automation
+    'Consumer Robot',      # Home robots, entertainment robots, and personal companions
+    'Defense/Government',  # Military, public safety, and national research programs
+    'Education',           # University courses, student projects, and teaching platforms
+    'Energy',              # Oil, gas, solar, nuclear, and power infrastructure operations
+    'Healthcare/Medical',  # Surgical robots, rehabilitation systems, and medical diagnostics
+    'Humanoid',            # Bipedal and human-form robots
+    'Logistics/Warehouse', # AMRs, inventory management, and last-mile delivery systems
+    'Manufacturing',       # Industrial automation, assembly lines, and quality control
+    'Marine',              # Underwater, surface, and coastal robotic systems
+    'Research',            # General academic, laboratory, or experimental research
+    'Space',               # Planetary rovers, orbital systems, and space exploration
+    'Service Robot',       # Hospitality, cleaning, retail, and public-facing service robots
+]
+
+# YYYY-MM-DD format for date_added field.
+_DATE_ADDED_RE = re.compile(r'^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$')
+
+REQUIRED_FIELDS = [
+    'organization',
+    'project',
+    'domain',
+    'date_added',
+    'country',
+    'description'
+]
+
+
+def validate_adopters(adopters):
+    """Validate a list of adopter entries. Returns list of error strings."""
+    errors = []
+    if not isinstance(adopters, list):
+        return ["'adopters' must be a list"]
+    for i, entry in enumerate(adopters):
+        prefix = (
+            f'Entry {i + 1} '
+            f'({entry.get("organization", "unknown")}/{entry.get("project", "unknown")})'
+        )
+        if not isinstance(entry, dict):
+            errors.append(f'{prefix}: must be a mapping')
+            continue
+        for field in REQUIRED_FIELDS:
+            if field not in entry or not entry[field]:
+                errors.append(f'{prefix}: missing required field "{field}"')
+        if 'domain' in entry and entry['domain']:
+            if not isinstance(entry['domain'], list):
+                errors.append(f'{prefix}: "domain" must be a list')
+            else:
+                for d in entry['domain']:
+                    if d not in VALID_DOMAINS:
+                        errors.append(
+                            f'{prefix}: invalid domain "{d}". '
+                            f'Must be one of: {", ".join(VALID_DOMAINS)}'
+                        )
+        if 'date_added' in entry and entry['date_added']:
+            date_str = str(entry['date_added'])
+            if not _DATE_ADDED_RE.match(date_str):
+                errors.append(
+                    f'{prefix}: "date_added" must be in YYYY-MM-DD format, '
+                    f'got "{date_str}"'
+                )
+        if 'country' in entry and entry['country']:
+            if not isinstance(entry['country'], list):
+                errors.append(f'{prefix}: "country" must be a list')
+            else:
+                for code in entry['country']:
+                    if not isinstance(code, str) or len(code) != 2 or not code.isalpha():
+                        errors.append(
+                            f'{prefix}: each "country" entry must be a 2-letter '
+                            f'ISO 3166-1 alpha-2 code, got "{code}"'
+                        )
+    return errors

plugins/sphinx_adopters.py

@@ -0,0 +1,199 @@
+# Copyright 2026 Sony Group Corporation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Sphinx extension to render and validate the ROS 2 adopters YAML file. """
+
+import os
+
+import yaml
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx.errors import ExtensionError
+
+from adopters_schema import validate_adopters
+
+
+def _escape(text):
+    """Escape HTML special characters."""
+    if text is None:
+        return ''
+    return (
+        str(text)
+        .replace('&', '&')
+        .replace('<', '&lt;')
+        .replace('>', '&gt;')
+        .replace('"', '&quot;')
+    )
+
+
+def _make_link(text, url):
+    """Create an HTML link if url is provided, otherwise plain text."""
+    escaped_text = _escape(text)
+    if url:
+        escaped_url = _escape(url)
+        return f'<a href="{escaped_url}" target="_blank" rel="noopener">{escaped_text}</a>'
+    return escaped_text
+
+
+class AdoptersTableDirective(Directive):
+    """Directive to render the adopters YAML as a filterable HTML table."""
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    option_spec = {}
+
+    def run(self):
+        env = self.state.document.settings.env
+        # Locate adopters.yaml relative to the source file containing the directive.
+        source_dir = os.path.dirname(env.doc2path(env.docname))
+        yaml_path = os.path.join(source_dir, 'adopters.yaml')
+
+        if not os.path.isfile(yaml_path):
+            raise ExtensionError(
+                f'adopters.yaml not found at {yaml_path}'
+            )
+
+        # Register adopters.yaml as a dependency so incremental builds
+        # detect changes and re-read the directive.
+        env.note_dependency(yaml_path)
+
+        with open(yaml_path, 'r') as f:
+            data = yaml.safe_load(f)
+
+        adopters = data.get('adopters', [])
+        errors = validate_adopters(adopters)
+        if errors:
+            raise ExtensionError(
+                'Adopters YAML validation failed:\n' + '\n'.join(f'  - {e}' for e in errors)
+            )
+
+        # Sort by date_added descending (newest first), then organization name (A-Z).
+        adopters.sort(key=lambda a: a.get('organization', '').lower())
+        adopters.sort(key=lambda a: a.get('date_added', ''), reverse=True)
+
+        # Collect unique values for filters.
+        all_domains = sorted({d for a in adopters for d in a.get('domain', [])})
+        all_countries = sorted({c for a in adopters for c in a.get('country', [])})
+
+        # Build HTML.
+        html_parts = []
+
+        # Filter controls.
+        html_parts.append('<div class="adopters-filters">')
+        html_parts.append('<label for="adopters-filter-domain">Domain:</label>')
+        html_parts.append('<select id="adopters-filter-domain">')
+        html_parts.append('<option value="">All</option>')
+        for d in all_domains:
+            html_parts.append(f'<option value="{_escape(d)}">{_escape(d)}</option>')
+        html_parts.append('</select>')
+
+        html_parts.append('<label for="adopters-filter-country">Country:</label>')
+        html_parts.append('<select id="adopters-filter-country">')
+        html_parts.append('<option value="">All</option>')
+        for c in all_countries:
+            html_parts.append(f'<option value="{_escape(c)}">{_escape(c)}</option>')
+        html_parts.append('</select>')
+
+        html_parts.append('<label for="adopters-filter-search">Search:</label>')
+        html_parts.append(
+            '<input type="text" id="adopters-filter-search" placeholder="Filter by keyword...">'
+        )
+
+        # Show-all-history toggle.
+        html_parts.append(
+            '<label class="adopters-toggle-label">'
+            '<input type="checkbox" id="adopters-show-all">'
+            ' Show all history'
+            '</label>'
+            '<span class="adopters-filter-note">'
+            'Showing entries from the past 3 years. '
+            'Check &ldquo;Show all history&rdquo; to see all entries.'
+            '</span>'
+        )
+
+        html_parts.append('</div>')
+
+        # Table.
+        html_parts.append('<table class="adopters-table">')
+        html_parts.append('<thead><tr>')
+        html_parts.append('<th>Organization</th>')
+        html_parts.append('<th>Project</th>')
+        html_parts.append('<th>Domain</th>')
+        html_parts.append('<th>Date Added</th>')
+        html_parts.append('<th>Country</th>')
+        html_parts.append('<th>Description</th>')
+        html_parts.append('</tr></thead>')
+        html_parts.append('<tbody>')
+
+        for adopter in adopters:
+            org = _make_link(
+                adopter.get('organization', ''),
+                adopter.get('organization_url'),
+            )
+            project = _make_link(
+                adopter.get('project', ''),
+                adopter.get('project_url'),
+            )
+            domains = ', '.join(adopter.get('domain', []))
+            date_added = adopter.get('date_added', '')
+            countries = adopter.get('country', [])
+            country_str = ', '.join(countries)
+            description = _escape(adopter.get('description', ''))
+
+            # Data attributes for filtering.
+            data_domains = ' '.join(_escape(d) for d in adopter.get('domain', []))
+            data_countries = ' '.join(_escape(c) for c in countries)
+            html_parts.append(
+                f'<tr data-domains="{data_domains}" '
+                f'data-date-added="{_escape(str(date_added))}" '
+                f'data-countries="{data_countries}">'
+            )
+            html_parts.append(f'<td>{org}</td>')
+            html_parts.append(f'<td>{project}</td>')
+            html_parts.append(f'<td>{_escape(domains)}</td>')
+            html_parts.append(f'<td>{_escape(str(date_added))}</td>')
+            html_parts.append(f'<td>{_escape(country_str)}</td>')
+            html_parts.append(f'<td>{description}</td>')
+            html_parts.append('</tr>')
+
+        html_parts.append('</tbody></table>')
+
+        raw_node = nodes.raw('', '\n'.join(html_parts), format='html')
+        return [raw_node]
+
+
+_ADOPTERS_DOCNAME = 'The-ROS2-Project/Adopters/Adopters'
+
+
+def _get_outdated(app, env, _added, _changed, _removed):
+    """Force rebuild of the Adopters page when adopters.yaml changes."""
+    yaml_path = os.path.join(app.srcdir, 'The-ROS2-Project', 'Adopters', 'adopters.yaml')
+    if not os.path.isfile(yaml_path):
+        return []
+    doctree_path = os.path.join(app.doctreedir, _ADOPTERS_DOCNAME + '.doctree')
+    if os.path.isfile(doctree_path):
+        if os.path.getmtime(yaml_path) > os.path.getmtime(doctree_path):
+            return [_ADOPTERS_DOCNAME]
+    return []
+
+
+def setup(app):
+    app.add_directive('adopters-table', AdoptersTableDirective)
+    app.connect('env-get-outdated', _get_outdated)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

source/The-ROS2-Project.rst

@@ -17,3 +17,5 @@ Check out the resources below to learn more about the advancement of the ROS 2 p
    The-ROS2-Project/Release-Schedule
    The-ROS2-Project/Marketing
    The-ROS2-Project/Metrics
+   The-ROS2-Project/Adopters/Adopters
+   The-ROS2-Project/Adopters/Add-Your-Project