Merge branch '2.0' into 2.0-migration-guide-plus

Author: colleenXu

.github/workflows/docgen.yml

@@ -0,0 +1,30 @@
+---
+name: Generate Reference
+on:
+  pull_request:
+  push:
+    branches: [master, main, 'v?[0-9]+.[0-9]+']
+jobs:
+  docgen:
+    name: Run generator script
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - name: Install deps
+        run: |
+          pip install -r docs/requirements.txt
+      - name: Run script
+        run: python docs/generate_reference.py ${{ github.head_ref || github.ref_name }}
+      - name: commit changes
+        uses: stefanzweifel/git-auto-commit-action@v7
+        with:
+          commit_message: Update docs/reference.md [no ci]
+          file_pattern: docs/reference.md

.github/workflows/pr-checks.yml

@@ -3,7 +3,7 @@ name: PR checks
 on:
   pull_request:
   push:
-    branches: [master, main, 'v?[0-9]+.[0-9]+**']
+    branches: [master, main, 'v?[0-9]+.[0-9]+']
 jobs:
   linting:
     name: Check Yamllint

TranslatorReasonerAPI.yaml

@@ -801,7 +801,6 @@ components:
       additionalProperties: true
       required:
         - nodes
-        - edges
     QueryGraph:
       type: object
       description: >-
@@ -917,7 +916,7 @@ components:
             to AND)
           items:
             $ref: '#/components/schemas/AttributeConstraint'
-          default: []
+          minItems: 1
       additionalProperties: true
     QEdge:
       type: object

docs/generate_reference.py

@@ -1,15 +1,19 @@
 """Generate README."""
-import os
+
+from pathlib import Path
 import re
+import sys
+from typing import Any, Hashable, override
 
 from jinja2 import Environment, FileSystemLoader
 import yaml
 from yaml.loader import SafeLoader
 
-THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+# So we can ensure we're going a directory up for the yaml
+SCRIPT_DIR = Path(__file__).absolute().parent
 
 
-def link_refs(string):
+def link_refs(string: str) -> str:
     """Hyperlink refs."""
     return re.sub(
         r"\"\$ref\": \"#/components/schemas/(\w+)\"",
@@ -19,44 +23,46 @@ def link_refs(string):
 
 
 class SafeLineLoader(SafeLoader):
-    def construct_mapping(self, node, deep=False):
+    @override
+    def construct_mapping(
+        self, node: yaml.MappingNode, deep: bool = False
+    ) -> dict[Hashable, Any]:
         mapping = super().construct_mapping(node, deep=deep)
         # Add 1 so line numbering starts at 1
-        mapping['_start'] = node.start_mark.line
-        mapping['_end'] = node.end_mark.line
+        mapping["_start"] = node.start_mark.line
+        mapping["_end"] = node.end_mark.line
         return mapping
 
 
 def main():
     """Generate README."""
-    yamlpath = os.path.join(
-        THIS_DIR,
-        "TranslatorReasonerAPI.yaml",
-    )
+    yamlpath = SCRIPT_DIR.parent.joinpath("TranslatorReasonerAPI.yaml")
 
     j2_env = Environment(
-        loader=FileSystemLoader(THIS_DIR),
+        loader=FileSystemLoader(SCRIPT_DIR),
         trim_blocks=False,
         keep_trailing_newline=True,
         extensions=[
             "jinja2.ext.do",
-        ]
+        ],
     )
 
-    with open(yamlpath, 'r') as stream:
+    with yamlpath.open("r") as stream:
         data = yaml.load(stream, Loader=SafeLineLoader)
-    components = data['components']
-    schemas = components['schemas']
+    components = data["components"]
+    schemas = components["schemas"]
 
     sha = "master"
+    if len(sys.argv) >= 2:
+        sha = sys.argv[1]
 
-    markdown = j2_env.get_template('reference_template.md').render(
+    markdown = j2_env.get_template("reference_template.md").render(
         schemas=schemas,
         sha=sha,
     )
 
-    with open('reference.md', 'w') as stream:
-        stream.write(markdown.encode('cp850', 'replace').decode('utf-8', 'replace'))
+    with SCRIPT_DIR.joinpath("reference.md").open("w") as stream:
+        _ = stream.write(markdown)
 
 
 if __name__ == "__main__":