Merge pull request #617 from bioimage-io/friendly_json_schema

Adds scripts for generating json schemas for humans

.github/workflows/build.yml

@@ -59,12 +59,14 @@ jobs:
           pip install -e .[dev]
       - name: Generate spec docs
         run: python scripts/generate_spec_documentation.py --dist dist/user_docs
-      - name: Generate JSON schemas
-        run: python scripts/generate_json_schemas.py
       - name: Generate interactive documentation
         env:
           PYTHONPATH: "./scripts"
         run: python -m interactive_docs
+      - name: Generate JSON schemas
+        run: python scripts/generate_json_schemas.py
+      - name: Generate JSON schema documentation
+        run: python scripts/generate_json_schema_documentation.py
       - id: get_version
         run: python -c 'import bioimageio.spec;print(f"version={bioimageio.spec.__version__}")' >> $GITHUB_OUTPUT
       - name: Generate developer docs

README.md

@@ -43,10 +43,10 @@ Simplified descriptions are available as [JSON schema](https://json-schema.org/)
 
 | bioimageio.spec version | JSON schema |
 | --- | --- |
-| latest | [bioimageio_schema_latest.json](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_latest.json) |
-| 0.5 | [bioimageio_schema_v0-5.json](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_v0-5.json) |
+| latest | [bioimageio_schema_latest.json](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_latest.json) ([documentation (WIP)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_latest/index.html))|
+| 0.5 | [bioimageio_schema_v0-5.json](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_v0-5.json) ([documentation (WIP)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_v0-5/index.html))|
 
-These are primarily intended for syntax highlighting and form generation.
+These are primarily intended for syntax highlighting.
 
 ## Flattened, interactive docs
 

conda-recipe/meta.yaml

@@ -33,7 +33,9 @@ test:
     - example_descriptions
   requires:
     {% for dep in setup_py_data['extras_require']['dev'] %}
+    {% if dep not in ('json_schema_for_humans',): %}
     - {{ dep.replace('torch', 'pytorch').lower() }}
+    {% endif %}
     {% endfor %}
   commands:
     - pytest -n auto --capture=no

scripts/generate_json_schema_documentation.py

@@ -0,0 +1,38 @@
+import shutil
+import sys
+from pathlib import Path
+
+from json_schema_for_humans.generate import generate_from_filename
+from json_schema_for_humans.generation_configuration import GenerationConfiguration
+
+if __name__ == "__main__":
+    glob_pattern = "dist/bioimageio_schema_*.json"
+    schema_paths = list(Path().glob(glob_pattern))
+    if not schema_paths:
+        raise FileNotFoundError(
+            f"no json schema files found with pattern '{glob_pattern}'"
+        )
+
+    for schema_file_path in schema_paths:
+        output_dir = Path() / f"dist/{schema_file_path.stem}"
+        if output_dir.exists():
+            shutil.rmtree(output_dir)
+
+        output_dir.mkdir(parents=True)
+
+        generate_from_filename(
+            schema_file_name=schema_file_path,
+            result_file_name=str(output_dir / "index.html"),
+            config=GenerationConfiguration(
+                link_to_reused_ref=False,
+                deprecated_from_description=True,
+                default_from_description=True,
+                examples_as_yaml=True,
+                expand_buttons=True,
+                description_is_markdown=True,
+                copy_css=True,
+                copy_js=True,
+            ),
+        )
+
+        print(f"Generated json schema docs at {output_dir}", file=sys.stderr)

setup.py

@@ -1,7 +1,10 @@
 import json
 from pathlib import Path
 
-from setuptools import find_namespace_packages, setup
+from setuptools import (
+    find_namespace_packages,
+    setup,  # pyright: ignore[reportUnknownVariableType]
+)
 
 # Get the long description from the README file
 ROOT_DIR = Path(__file__).parent.resolve()
@@ -55,6 +58,7 @@
             "jupyter",
             "lxml",
             "pdoc",
+            "json_schema_for_humans",
             "pre-commit",
             "psutil",  # parallel pytest with '-n auto'
             "pyright==1.1.378",