docs: refresh internal guidance and dynamic specification references

.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

@@ -42,3 +42,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.

PROJECTS.md

@@ -4,7 +4,7 @@ Six core libraries provide building blocks for accelerated computing. Choose by
 the work you need to do, then use the project's documentation for installation,
 examples and supported platforms.
 
-[Foundation home](README.md) · [Working Group](https://github.com/uxlfoundation/open-source-working-group) · [oneAPI specification](https://uxlfoundation.org/specifications/oneapi/technical-overview/)
+[Foundation home](README.md) · [Working Group](https://github.com/uxlfoundation/open-source-working-group) · [Dynamic oneAPI specification](https://uxlfoundation.org/specifications/oneapi/technical-overview/)
 
 ## Choose a library
 

README.md

@@ -64,7 +64,7 @@ are available for [Image](image/README.rst) and
 | --- | --- |
 | [Foundation charter](doc/uxl-foundation-charter.rst) | Mission, projects and participation |
 | [Steering Committee](steering-committee/README.rst) | Governance and published meeting minutes |
-| [oneAPI specification](https://uxlfoundation.org/specifications/oneapi/technical-overview/) | Dynamic specification and links to current project documentation |
+| [Dynamic oneAPI specification](https://uxlfoundation.org/specifications/oneapi/technical-overview/) | Dynamic specification and links to current project documentation |
 | [Community operations](doc/README.rst) | Meeting guidance, GitHub, Slack and web hosting |
 | [Status report archive](monthly-status/) | Dated foundation updates |
 

ai-and-scientific-computing/2024-03-14-UXL-AI-SIG.rst

@@ -3,22 +3,22 @@ AI Special Interest Group Meeting Notes
 =========================================
 
 2024-03-14
-==========
+============
 
-Attendees 
+Attendees
 
 * Nikolay Petrov (Intel)
 * Darshan Patel (Fujitsu)
-* Daniel Holmes 
+* Daniel Holmes
 * Abhishek Nair (Fujitsu)
 * Mourad Gouicem (Intel)
-* Shashank Sangu 
+* Shashank Sangu
 * Giovanni Grandi (Codasip s.r.o.)
-* Jose Fonseca 
+* Jose Fonseca
 * Deeksha Goplani (Fujitsu)
 * Rumpf Mr
 * Mehdi Goli (Codeplay)
-* John Melonakos 
+* John Melonakos
 * Alison Richards (Intel)
 * Balas, DorotheeX Marie Clotilde
 * Chandan Sharma  (Fujitsu)
@@ -30,43 +30,44 @@ Attendees
 * Peter Robertson (Codasip s.r.o.)
 * Ronan Keryell (AMD)
 * Ruyman Reyes Castro (Codeplay)
-* Sasank Chilamkurthy 
+* Sasank Chilamkurthy
 * Dave Murray (Imagination Technologies)
 * Jianhui Li (Intel)
-* Kevan Ahmadi 
+* Kevan Ahmadi
 * Roman Zhukov (Intel)
 * Rod Burns (Codeplay)
 * Chao Chen (Intel)
 * Nishant Prabhu (Fujitsu)
-* Stephen Porter 
+* Stephen Porter
 * Robert Cohn (Intel)
 * Divya Kota (Accenture)
 * Charles Tuke (Imagination Technologies)
 * Priyanka Sharma (Fujitsu)
 * Md. Abdullah Shahneous Bari (Intel)
 * Masahiro Doteguchi (Fujitsu)
 * Penporn Koanantakool (Google)
-Agenda - 
-
+
+Agenda -
+
 * Enabling oneDAL on ARM target    Chandan Sharma (`slides <presentations/20240314-UXL-oneDAL-ARM-SVE-Enablement_ChandanSharma.pdf>`__)
 * oneDNN overview and update       Mourad Gouicem (`slides <presentations/20240314-UXL-oneDNN-Overview-And-Developments_MouradGouicem.pdf>`__)
-* Discussion (motivation, expectation, future topics) 
+* Discussion (motivation, expectation, future topics)
+
+Question: Fujitsu extended oneDAL to use OpenBLAS library to enable ARM target.  oneDAL uses private MKL interface.  Will oneDAL use public MKL interface?
+Will MKL be open source?
 
-Question: Fujitsu extended oneDAL to use OpenBLAS library to enable ARM target.  oneDAL uses private MKL interface.  Will oneDAL use public MKL interface? 
-Will MKL be open source?  
+Answer:  oneDAL uses MKL interface as it needs to use the SYCL interface.  oneDAL plans to use oneMKL interface and MKL can be its backend math library. There is no plan to open source MKL.
 
-Answer:  oneDAL uses MKL interface as it needs to use the SYCL interface.  oneDAL plans to use oneMKL interface and MKL can be its backend math library. There is no plan to open source MKL.  
+Question: What is the reason of using OpenBlas, not ARM compute library (ACL)?
 
-Question: What is the reason of using OpenBlas, not ARM compute library (ACL)?  
-
-Answer: Fujisu choose OpenBlas because OpenBlas is more “Open”. 
+Answer: Fujisu choose OpenBlas because OpenBlas is more “Open”.
 
-Answer: I am Christopher Rumph and part of UXL steering committee as ARM representative.  ARM compute library is open source project, but not run as “open governance” model.  I can help discuss with ARM colleagues to enable you on what you try to achieve.  Potentially ACL could be oneMKL’s backend.  
+Answer: I am Christopher Rumph and part of UXL steering committee as ARM representative.  ARM compute library is open source project, but not run as “open governance” model.  I can help discuss with ARM colleagues to enable you on what you try to achieve.  Potentially ACL could be oneMKL’s backend.
 
-Question: Is oneDNN Graph API stable and officially supported? 
+Question: Is oneDNN Graph API stable and officially supported?
 
-Answer:  Yes. oneDNN Graph is an official feature of oneDNN. oneDNN Graph API is stable API, and there is an official backend using oneDNN primitives.  The oneDNN Graph compiler backend is an experimental feature. 
+Answer:  Yes. oneDNN Graph is an official feature of oneDNN. oneDNN Graph API is stable API, and there is an official backend using oneDNN primitives.  The oneDNN Graph compiler backend is an experimental feature.
 
-Question:  What does it take to optimize oneDNN to other targets? 
+Question:  What does it take to optimize oneDNN to other targets?
 
 Answer: There are three levels. The first approach is to map the API to external library (e.g. ARM backend relies on ACL, Nvidia backend relies on cuDNN/cuBLAS, ...), the second one is to add C++/SYCL implementations with targeted optimizations (e.g. RISC-V RVV optimized Matmul), and the third one is to add jitting capabilites and jit kernel generators (e.g. x64 support contributed by Intel and SVE support contributed by Fujitsu).

ai-and-scientific-computing/2025-12-19-UXL-AI-SIG.rst

@@ -3,7 +3,7 @@
 =========================================
 
 2025-12-19
-=========
+============
 Attendees
 
 * Biagio COSENZA (University of Salerno)
@@ -22,15 +22,15 @@ Attendees
 * Alison Richards (Intel Corporation)
 * En Shao (University of Chinese Academy of Sciences)
 
-======
+========
 Agenda
-======
+========
 
 **NVIDIA GPU Adaptation for SYCL-MLIR**, **Boyuan Bao**, Beijing Institute of Open Source Chip, (`slides <presentations/2025-12-19-NVIDIA-GPU_ADAPTATION_FOR_SYCL-MLIR_BoYuan.pdf>`__)
 
 
 Background and Motivation
-=========================
+===========================
 
 - **SYCL-MLIR** is an MLIR-based compiler infrastructure for SYCL and heterogeneous
   programming, designed to keep host code and device kernels in the same MLIR
@@ -43,10 +43,10 @@ Background and Motivation
   later shelved internally and is no longer actively maintained.
 
 Technical Contributions
-=======================
+=========================
 
 NVIDIA Built-in Variable Adaptation
------------------------------------
+-------------------------------------
 
 - The generated LLVM IR contained references to SPIR-V built-in variables
   (e.g., thread and block IDs, execution parameters).
@@ -62,15 +62,15 @@ NVIDIA Built-in Variable Adaptation
   while providing a cleaner abstraction.
 
 Kernel Entry Point Handling
----------------------------
+-----------------------------
 
 - Kernel attributes were added to ensure that backend compilation pipelines
   correctly identify kernel entry points.
 - Without these attributes, later compilation stages would fail to recognize
   device kernels.
 
 Pipeline Integration
---------------------
+----------------------
 
 - The current compilation flow is not yet fully unified:
   - Front-end: SYCL source is lowered to MLIR/LLVM using existing front-end tooling (e.g., cgeist-based flow).
@@ -79,31 +79,31 @@ Pipeline Integration
   stages, enabling generation of executable binaries for NVIDIA GPUs.
 
 Results and Validation
-=====================
+========================
 
 - Correctness was validated using **SYCLBench** and **PolyBench** test suites.
 - Most benchmarks executed successfully on NVIDIA GPUs.
 - No performance evaluation was conducted in this phase.
   The focus was on functional correctness and backend enablement.
 
 Q&A and Strategic Discussion
-============================
+==============================
 
 Performance Evaluation
-----------------------
+------------------------
 
 - **Ettore Tiotto** noted that performance comparison against a baseline
   (without SYCL-MLIR translation) would be a natural next step.
 - The presenters confirmed that performance analysis has not yet been performed.
 
 Future Backend Support
-----------------------
+------------------------
 
 - The team plans to explore additional backends, including **AMD GPUs**.
 - It was noted that the AMD path should be similar, using ROCDL-based lowering.
 
 Maintenance and Upstreaming Strategy
-------------------------------------
+--------------------------------------
 
 - The team asked whether to contribute the NVIDIA backend through Intel’s existing
   repository or via UXL processes.
@@ -112,7 +112,7 @@ Maintenance and Upstreaming Strategy
   - Forking removes reliance on Intel-internal CI infrastructure and enables independent CI coverage across a broader hardware ecosystem.
 
 Front-end Considerations
-------------------------
+--------------------------
 
 - **Whitney** asked whether replacing the current front-end (cgeist) with a more
   standardized MLIR-based front-end such as CIR (Clang IR) was being considered.
@@ -122,7 +122,7 @@ Front-end Considerations
   prototyping or long-term productization.
 
 UXL Foundation Process for Adding a Repository
-----------------------------------------------
+------------------------------------------------
 
 - **Penporn Koanantakool (Google)** and **Alison Richards (Intel)** explained that
   proposals for hosting a repository under the UXL Foundation should be brought
@@ -132,7 +132,7 @@ UXL Foundation Process for Adding a Repository
   in determining whether a project is suitable to be hosted under UXL.
 
 Announcements
-=============
+===============
 
 - **UXL Foundation Members Meeting**
   - Date: **January 15**