docs: clarify CI inventory and repair specification and meeting records

.github/meeting-notes-template.rst

@@ -1,28 +1,28 @@
 Meeting title
-=============
+===============
 
 Date: YYYY-MM-DD
 
 Attendees
----------
+-----------
 
 Agenda
-------
+--------
 
 Discussion
-----------
+------------
 
 Decisions
----------
+-----------
 
 Record approved decisions separately from proposals and open questions.
 
 Actions
--------
+---------
 
 For each action, record the agreed owner, next step and target date or issue.
 
 Materials and recording
-----------------------
+-------------------------
 
 Add presentation links and recording access details. Update the meeting index.

.github/scripts/check_document_structure.py

@@ -0,0 +1,49 @@
+"""Validate RST rendering and coverage of dated records in sibling indexes."""
+import io
+from pathlib import Path
+import re
+import sys
+from docutils import nodes
+from docutils.core import publish_doctree
+
+
+def check(root):
+    errors = []
+    retired = re.compile(
+        r'https?://(?:spec\.oneapi\.(?:com|io)|oneapi-spec\.uxlfoundation\.org)'
+        r'|https?://(?:github\.com|uxlfoundation\.github\.io)/[^\s<>]*'
+        r'(?:oneapi-spec(?:[/#?]|\b)|spec-working-group)'
+        r'|specification\s+working\s+group', re.IGNORECASE)
+    for path in root.rglob('*'):
+        if path.suffix not in {'.md', '.rst'} or '.git' in path.relative_to(root).parts:
+            continue
+        for number, line in enumerate(path.read_text(encoding='utf-8').splitlines(), 1):
+            if retired.search(line):
+                errors.append(f'{path.relative_to(root)}:{number}: retired specification reference; use the UXL dynamic specification')
+    for path in sorted(root.rglob('*.rst')):
+        if '.git' in path.relative_to(root).parts:
+            continue
+        source = path.read_text(encoding='utf-8')
+        tree = publish_doctree(source, settings_overrides={
+            'halt_level': 6, 'report_level': 5, 'warning_stream': io.StringIO(),
+            'raw_enabled': False, 'file_insertion_enabled': False,
+        })
+        for message in tree.findall(nodes.system_message):
+            if message['level'] >= 2:
+                errors.append(f'{path.relative_to(root)}:{message.get("line", "?")}: {message.astext()}')
+        if re.match(r'\d{4}-\d', path.name):
+            index = path.parent / 'README.rst'
+            if index.exists():
+                # Match actual inline links, not incidental mentions of the filename.
+                links = re.findall(r'<([^<>\n]+)>`_{1,2}', index.read_text(encoding='utf-8'))
+                if path.name not in links:
+                    errors.append(f'{path.relative_to(root)}: missing from {index.relative_to(root)}')
+    return errors
+
+
+if __name__ == '__main__':
+    errors = check(Path.cwd())
+    for error in errors:
+        print(error)
+    print(f'Document structure: {len(errors)} error(s).')
+    sys.exit(bool(errors))

.github/scripts/test_document_structure.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+import tempfile
+import unittest
+from check_document_structure import check
+
+
+class StructureChecks(unittest.TestCase):
+    def test_retired_destination_and_current_specification(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            page = root / 'README.md'
+            page.write_text('[Spec](https://github.com/uxlfoundation/oneAPI-spec)\n', encoding='utf-8')
+            self.assertTrue(any('retired specification' in e for e in check(root)))
+            page.write_text('[Spec](https://uxlfoundation.org/specifications/oneapi/technical-overview/)\n', encoding='utf-8')
+            self.assertEqual(check(root), [])
+
+    def test_malformed_heading(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / 'README.rst').write_text('Long heading\n==========\n', encoding='utf-8')
+            self.assertTrue(check(root))
+
+    def test_wrong_existing_record_does_not_cover_omitted_record(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            for date in ['2024-09-05', '2024-09-19']:
+                (root / f'{date}.rst').write_text('Meeting\n=======\n', encoding='utf-8')
+            index = root / 'README.rst'
+            index.write_text('`September 5 <2024-09-05.rst>`__\n\n'
+                             '`September 19 <2024-09-05.rst>`__\n', encoding='utf-8')
+            self.assertTrue(any('2024-09-19.rst: missing' in e for e in check(root)))
+            index.write_text('`September 5 <2024-09-05.rst>`__\n\n'
+                             '`September 19 <2024-09-19.rst>`__\n', encoding='utf-8')
+            self.assertEqual(check(root), [])
+
+
+if __name__ == '__main__':
+    unittest.main()

.github/workflows/docs.yml

@@ -14,7 +14,11 @@ jobs:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
           persist-credentials: false
-      - name: Test link checker
+      - name: Install documentation parser
+        run: python3 -m pip install docutils==0.19
+      - name: Test documentation checks
         run: python3 -m unittest discover -s .github/scripts -p 'test_*.py'
       - name: Check local links
         run: python3 .github/scripts/check_local_links.py
+      - name: Check document structure
+        run: python3 .github/scripts/check_document_structure.py

CONTRIBUTING.md

@@ -41,3 +41,8 @@ a new license or change governance or contribution terms. Ask foundation
 operations to confirm applicable terms before importing third-party material.
 Report security vulnerabilities through the affected project's private reporting
 channel or security policy, rather than posting details in a public issue.
+
+For rendering and meeting-index checks, install `docutils==0.19` and run
+`python .github/scripts/check_document_structure.py`. The check reports malformed
+reStructuredText and dated records missing from sibling indexes. External URLs
+and cross-document section anchors still require review.

README.rst

@@ -76,9 +76,9 @@ About this group
 ----------------
 
 This repository coordinates both specification and implementation work within the
-`UXL Foundation`_. The former `Specification Working Group archive`_ preserves
-earlier discussions and RFCs. Current proposals belong here or in the relevant
-project repository.
+`UXL Foundation`_. Current specification concepts are maintained on the UXL
+website, with APIs and requirements defined by each project's documentation.
+Proposals belong here or in the relevant project repository.
 
 
 .. _`Latest meeting`: meetings/notes/2026-08-19.rst
@@ -95,7 +95,6 @@ project repository.
 .. _`openprofile account`: https://openprofile.dev/
 .. _`UXL Slack`: https://slack-invite.uxlfoundation.org/
 .. _`UXL Foundation`: https://github.com/uxlfoundation/foundation
-.. _`Specification Working Group archive`: https://github.com/uxlfoundation/spec-working-group
 
 .. |uxl-logo| image:: https://raw.githubusercontent.com/uxlfoundation/artwork/e98f1a7a3d305c582d02c5f532e41487b710d470/foundation/uxl-foundation-icon-color.png
    :alt:

meetings/notes/2024-01-24.rst

@@ -1,8 +1,8 @@
 1/24/2024
-=========
+===========
 
 Attendees:
-----------
+------------
 
 * Andrew Wafaa, Arm (Open Source Working Group chair)
 * Abhishek Jain, Fujitsu
@@ -24,13 +24,13 @@ Attendees:
 * Vadim Pirogov, Intel
 
 Agenda:
--------
+---------
 
 * Present priorities for the Open Source Working Group
 * Discuss issues and areas for work
 
 Notes
------
+--------
 
 The first meeting of the UXL Foundation Open Source Working Group was
 led by Andrew Wafaa from Arm.
@@ -39,49 +39,57 @@ The group went through a set of priorities that have been provided by
 the UXL Steering Committee.
 
 * Build Infrastructure
+
   * The intention of this is to bring independent builds of the
     projects and infrastructure in place that facilitates community
     contributions to the projects.
 
 * Open Source Best Practice
+
   * The intention of this is to ensure that the projects follow the
     best practices of open source development so that there is a clear
     and frictionless way for the community to contribute to the
     projects.
 
 * Open Source Kernels
+
   * The intention of this is to bring more open source code to the
     projects where there are opportunities to add new kernel code
     particularly to help target more vendors and architectures.
 
 * Architecture
+
   * Identify opportunities to simplify projects or make it easier to
     support more vendor and architecture targets and also to simplify
     the integration of the projects with other frameworks and
     software, for example TensorFlow or PyTorch.
 
 * Compatibility Testing
+
   * In order to ensure that a developer using the projects has a
     consistent and good experience, compatibility tests could be made
     available so that they can be run on different vendors and
     architectures.
 
 
 * Build Infrastructure Discussion
+
   * Due to the history of the projects the infrastructure is mostly
     hosted by Intel but we would like to integrate CI, build and
     testing for different vendor and architecture targets.  Penporn
     from Google shared information about how this is done with the
     TensorFlow project:
+
     * `Official Builds (maintained by Google)`_
+
     * `Community Builds (maintained by 3rd parties)`_
 
 A similar model could be adopted for UXL Foundation projects.  Options
 for using public cloud infrastructure for the projects include:
- 
+
 * The foundation funding infrastructure (this is unlikely due to the
   costs involved)
-* Obtaining donations of credits from public cloud infrastructure 
+* Obtaining donations of credits from public cloud infrastructure
   providers (note that donations cannot be used in lieu of membership cost)
 * Organisations providing infrastructure in a similar way to how Intel
   currently does this

meetings/notes/2024-03-26.rst

@@ -5,53 +5,72 @@
 John M. chaired the meeting. Andy could not attend because of travel.
 
 Attendees
-=========
+===========
 
-.. list-table:: 
+.. list-table::
 
-  * - Alexey Kukanov 
+  * - Alexey Kukanov
     - Intel Corporation
-  * - Maria Garzaran 
+
+  * - Maria Garzaran
     - Intel Corporation
-  * - Abhishek Jain 
+
+  * - Abhishek Jain
     - Fujitsu Limited
+
   * - Nikolay Petrov
     - Intel Corporation
+
   * - Jory Burson
     - The Linux Foundation
+
   * - Kasper Mecklenburg
     - Arm Limited
+
   * - Ruyman Reyes Castro
     - Codeplay Software
+
   * - Ragesh Hajela
     - Fujitsu Limited
+
   * - Ankit Manerikar
     - Intel Corporation
+
   * - Steve Capper
     - Arm Limited
+
   * - Rod Burns
     - Codeplay Software
+
   * - Joel Rosenzweig
     - Intel Corporation
+
   * - Roman Zhukov
     - Intel Corporation
+
   * - David Edelsohn
     - International Business Machines Corporation
+
   * - Stephano Cetola
     - Intel Corporation
+
   * - Alison Richards
     - Intel Corporation
+
   * - John Melonakos
     - Intel Corporation
+
   * - Balas, DorotheeX Marie Clotilde
     - Intel Corporation
+
   * - Robert Cohn
     - Intel Corporation
+
   * - Pavel Kumbrasev
     - Intel Corporation
 
 Security: Roman Z.
-==================
+====================
 
 * Roman gave an update on security
 * Group has formed and met once
@@ -67,18 +86,25 @@ Security: Roman Z.
 .. _`security work package`: https://github.com/orgs/uxlfoundation/projects/3
 
 Open Source recommendations: Rod B.
-===================================
+=====================================
 
 * Rod had a follow-up discussion about the findings from looking at
   the `Red Hat open source checklist`_.
+
   * `Summary spreadsheet`_
+
   * `oneMKL report`_
+
   * `oneDPL report`_
+
   * `oneDNN report`_
+
   * `oneCCL report`_
+
   * `oneDAL report`_
 
 * Q: More discussion about private vs public discussion.
+
   * Prioritize the kinds of information that other developers will
     need to know. Look at oneDNN RFC's as an example.
 
@@ -95,7 +121,7 @@ Open Source recommendations: Rod B.
 .. _`oneDAL report`: https://docs.google.com/document/d/1QRJVhcUv_JKSQmqlb43NkL37n5rliKw4
 
 GitHub Org Transition: Robert C.
-================================
+==================================
 
 * `GitHub Org Slides`_
 * We have to move GitHub repos to LF/UXLF ownership