write schema to sphinx to make it usable in editors

Author: mathiasertl

.readthedocs.yaml

@@ -24,7 +24,7 @@ build:
       - uv sync --group dev --group rtd
     pre_build:
       - ./fetch_swagger.sh
-      - uv run generate-schema.py
+      - uv run generate-schema.py -o > docs/_static/schema.json
     build:
       html:
         - uv run sphinx-build -T -b html docs/ $READTHEDOCS_OUTPUT/html

docs/changelog.rst

@@ -7,6 +7,7 @@ ChangeLog
 ***********
 
 * Alternatives now allow specific context and environment variables.
+* The JSON schema is now available `here <_static/schema.json>`_ and can be used in IDEs such as PyCharm.
 
 ******************
 0.3.0 (2025-12-26)

docs/quickstart.rst

@@ -27,6 +27,14 @@ To render your tutorials in Sphinx, add the extension and, optionally, where you
     # Location where your tutorials are stored (default: same directory as conf.py).
     #structured_tutorials_root = Path(__file__).parent / "tutorials"
 
+Editor integration
+==================
+
+The JSON schema is can be found `here <_static/schema.json>`_ and can be used in IDEs for auto-completion
+and validation. For example:
+
+* `PyCharm <https://www.jetbrains.com/help/pycharm/yaml.html#json_schema>`_
+
 
 *******************
 Your first tutorial

generate-schema.py

@@ -67,4 +67,7 @@ def generate_openapi_schema(
     fh.write(swagger_js)
 
 if args.output:
-    print(json.dumps(openapi, indent=4, sort_keys=True))
+    schema = TutorialModel.model_json_schema()
+    del schema["properties"]["path"]
+    schema["required"].remove("path")
+    print(json.dumps(schema, indent=4, sort_keys=True))