bioimage-io · FynnBe · Oct 10, 2024 · Aug 27, 2024 · Aug 27, 2024 · Aug 29, 2024
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -61,6 +61,10 @@ jobs:
  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
  - id: get_version
  run: python -c 'import bioimageio.spec;print(f"version={bioimageio.spec.__version__}")' >> $GITHUB_OUTPUT
  - name: Generate developer docs

diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ 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) |
+| 0.5 | [bioimageio_schema_v0-5.json](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/bioimageio_schema_v0-5.json) [rendered](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/interactive_docs_v0-5.html) |
 
 These are primarily intended for syntax highlighting and form generation.
 

diff --git a/bioimageio/spec/_internal/io.py b/bioimageio/spec/_internal/io.py
@@ -6,6 +6,7 @@
 import sys
 import warnings
 from abc import abstractmethod
+from collections.abc import Mapping as MappingAbc
 from dataclasses import dataclass
 from datetime import date as _date
 from datetime import datetime as _datetime
@@ -51,6 +52,7 @@
  LiteralString,
  NotRequired,
  Self,
+ TypeGuard,
  Unpack,
  assert_never,
 )
@@ -479,6 +481,28 @@ def ensure_is_valid_bioimageio_yaml_name(file_name: FileName) -> FileName:
 BioimageioYamlSource = Union[PermissiveFileSource, BioimageioYamlContent]
 
 
+def is_yaml_leaf_value(value: Any) -> TypeGuard[YamlLeafValue]:
+ return isinstance(value, (bool, _date, _datetime, int, float, str, type(None)))
+
+
+def is_yaml_list(value: Any) -> TypeGuard[List[YamlValue]]:
+ return isinstance(value, Sequence) and all(
+ is_yaml_value(item)
+ for item in value # pyright: ignore [reportUnknownVariableType]
+ )
+
+
+def is_yaml_mapping(value: Any) -> TypeGuard[BioimageioYamlContent]:
+ return isinstance(value, MappingAbc) and all(
+ isinstance(key, str) and is_yaml_value(val)
+ for key, val in value.items() # pyright: ignore [reportUnknownVariableType]
+ )
+
+
+def is_yaml_value(value: Any) -> TypeGuard[YamlValue]:
+ return is_yaml_leaf_value(value) or is_yaml_list(value) or is_yaml_mapping(value)
+
+
 @dataclass
 class OpenedBioimageioYaml:
  content: BioimageioYamlContent

diff --git a/scripts/interactive_docs/__init__.py b/scripts/interactive_docs/__init__.py
@@ -0,0 +1,54 @@
+from typing import Any, List
+from .hint import Hint, Unrecognized, Widget
+
+
+def generate_docs(*, raw_type: Any, root_path: List[str]) -> "str | Exception":
+ hint = Hint.parse(raw_hint=raw_type, parent_raw_hints=[])
+ if isinstance(hint, (Exception, Unrecognized)):
+ return Exception(f"Could not process {raw_type}: {hint}")
+
+ root_hint_widget = hint.to_type_widget(root_path)
+ assert isinstance(root_hint_widget, Widget), root_hint_widget
+
+ return f"""
+ <!doctype html>
+ <html>
+ <head>
+ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/school-book.min.css">
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/yaml.min.js"></script>
+ </head>
+ <script>
+ document.addEventListener("DOMContentLoaded", () => {{
+ if(location.hash){{
+ console.log("Expanding details and jumping to hash");
+ const target = document.getElementById(location.hash.slice(1));
+ if(!target){{
+ return
+ }}
+ let parent = target.parentElement;
+ while(parent){{
+ if(parent.tagName == "DETAILS"){{
+ parent.open = true;
+ }}
+ parent = parent.parentElement;
+ }}
+ target.scrollIntoView({{
+ behavior: 'smooth',
+ block: 'start',
+ }});
+ }}
+ }})
+ </script>
+ <style>
+ {Widget.get_css()}
+ </style>
+ <body>
+ {root_hint_widget.to_html()}
+ </body>
+ <script>
+ hljs.highlightAll();
+ </script>
+ </html>
+
+ """
diff --git a/scripts/interactive_docs/__main__.py b/scripts/interactive_docs/__main__.py
@@ -0,0 +1,28 @@
+from typing_extensions import assert_never
+import sys
+from pathlib import Path
+
+from bioimageio.spec import SpecificResourceDescr
+from scripts.generate_json_schemas import MAJOR_MINOR_VERSION
+
+from . import generate_docs
+
+
+html_result: "str | Exception" = generate_docs(
+ raw_type=SpecificResourceDescr, root_path=["Delivery"]
+)
+if isinstance(html_result, Exception):
+ print(f"Could not generate docs: {html_result}", file=sys.stderr)
+ exit(1)
+elif isinstance(html_result, str):
+ docs_output_path = (
+ Path(__file__).parent.parent.parent
+ / f"dist/interactive_docs_{MAJOR_MINOR_VERSION}.html"
+ )
+ docs_output_path.parent.mkdir(parents=True, exist_ok=True)
+ print(f"[INFO] Writing interactive docs to {docs_output_path}")
+ with open(docs_output_path, "w") as f:
+ _ = f.write(html_result)
+ print(f"Wrote {_} bytes to {docs_output_path}")
+else:
+ assert_never(html_result)