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",