Add a schema for validating .doc_config.yaml (#7)

* Add a schema for validating .doc_config.yaml

This is a simple JSON Schema for validating the .doc_config.yaml
files.

Additionally, add a mode for concatenating the `index.adoc` file for
an example page from fragments in the current directory -- this is
anticipated based on examination for the tar-and-transfer example,
which probably needs to be broken down into several files.

Writing the config to allow for this was an initial trial of the
schema's internal consistency and usability. As a side-effect of the
refactor, the 'readme_is_index' config was replaced with a config of
the form

    {"copy": "README.adoc"}

which will probably be the norm for examples, but about which we can
be flexible in the future.

With the schema in place, updates to the doc build script include the
removal of type checks, as we can rely on the schema to do this work.

* Minor tweaks per review

Author: sirosen

.pre-commit-config.yaml

@@ -26,6 +26,10 @@ repos:
     rev: 0.33.0
     hooks:
       - id: check-github-workflows
+      - id: check-jsonschema
+        args: ["--schemafile", "support/doc_config_schema.json"]
+        files: "\\.doc_config\\.yaml"
+        types: [yaml]
 
   - repo: "https://github.com/sirosen/texthooks"
     rev: 0.6.8

support/build-doc-bundle.py

@@ -68,18 +68,13 @@ def build_all_files() -> t.Iterator[tuple[str, bytes]]:
         config = load_config(config_file)
         all_example_configs.append(config)
 
-        if not config.readme_is_index:
-            _abort("doc builds currently only support readme_is_index behavior")
-
         for sub_path in ("definition.json", "input_schema.json", "sample_input.json"):
             with open(source_dir / sub_path, "rb") as fp:
                 yield f"{config.example_dir}/{sub_path}", fp.read()
-        with open(source_dir / "README.adoc", "rb") as fp:
-            content = fp.read()
-            if config.append_source_blocks:
-                content = append_source_blocks(content)
-            content = prepend_preamble(config, content)
-            yield f"{config.example_dir}/index.adoc", content
+
+        yield f"{config.example_dir}/index.adoc", render_example_index_doc(
+            source_dir, config
+        )
     yield "index.adoc", build_index_doc(all_example_configs)
 
 
@@ -88,6 +83,30 @@ def find_build_configs() -> t.Iterator[pathlib.Path]:
         yield pathlib.Path(item)
 
 
+def render_example_index_doc(
+    source_dir: pathlib.Path, config: ExampleDocBuildConfig
+) -> bytes:
+    content: bytes
+    if config.index_source.mode == "copy":
+        if len(config.index_source.filenames) != 1:
+            raise ValueError("A 'copy' config cannot have multiple filenames.")
+        content = (source_dir / config.index_source.filenames[0]).read_bytes()
+    elif config.index_source.mode == "concat":
+        content = b"".join(
+            (source_dir / filename).read_bytes()
+            for filename in config.index_source.filenames
+        )
+    else:
+        raise NotImplementedError(
+            f"Unsupported index_source mode: {config.index_source.mode}"
+        )
+
+    if config.append_source_blocks:
+        content = append_source_blocks(content)
+    content = prepend_preamble(config, content)
+    return content
+
+
 def prepend_preamble(config: ExampleDocBuildConfig, content: bytes) -> bytes:
     return (
         textwrap.dedent(
@@ -171,55 +190,51 @@ def build_index_doc(configs: list[ExampleDocBuildConfig]) -> bytes:
     return INDEX_TEMPLATE.render({"examples": sorted_configs}).encode("utf-8")
 
 
+def load_config(config_file: pathlib.Path) -> ExampleDocBuildConfig:
+    with open(config_file, "rb") as fp:
+        raw_config_data = yaml.safe_load(fp)
+
+    if not isinstance(raw_config_data, dict):
+        _abort(f"cannot fetch yaml data from {config_file}, non-dict config?")
+
+    return ExampleDocBuildConfig._load(raw_config_data)
+
+
 @dataclasses.dataclass
 class ExampleDocBuildConfig:
     title: str
     short_description: str
     example_dir: str
-    readme_is_index: bool
+    index_source: IndexSourceConfig
     append_source_blocks: bool
     menu_weight: int
 
+    @classmethod
+    def _load(cls, data: dict[str, t.Any]) -> t.Self:
 
-def load_config(config_file: pathlib.Path) -> ExampleDocBuildConfig:
-    filename: str = str(config_file)
-    with open(config_file, "rb") as fp:
-        raw_config_data = yaml.load(fp, Loader=yaml.Loader)
-
-    title: str = _require_yaml_type(filename, raw_config_data, "title", str)
-    short_description: str = _require_yaml_type(
-        filename, raw_config_data, "short_description", str
-    )
-
-    example_dir: str = _require_yaml_type(filename, raw_config_data, "example_dir", str)
-    readme_is_index: bool = _require_yaml_type(
-        filename, raw_config_data, "readme_is_index", bool
-    )
-    append_source_blocks: bool = _require_yaml_type(
-        filename, raw_config_data, "append_source_blocks", bool
-    )
-    menu_weight: int = _require_yaml_type(filename, raw_config_data, "menu_weight", int)
-
-    return ExampleDocBuildConfig(
-        title=title,
-        short_description=short_description,
-        example_dir=example_dir,
-        readme_is_index=readme_is_index,
-        append_source_blocks=append_source_blocks,
-        menu_weight=menu_weight,
-    )
-
+        return cls(
+            title=data["title"],
+            short_description=data["short_description"],
+            example_dir=data["example_dir"],
+            index_source=IndexSourceConfig._load(data["index_source"]),
+            append_source_blocks=data["append_source_blocks"],
+            menu_weight=data["menu_weight"],
+        )
 
-T = t.TypeVar("T")
 
-
-def _require_yaml_type(filename: str, data: t.Any, key: str, typ: type[T]) -> T:
-    if not isinstance(data, dict):
-        _abort("cannot fetch yaml data, non-dict config?")
-    value = data.get(key)
-    if not isinstance(value, typ):
-        _abort(f"{filename}::$.{key} must be of type '{typ.__name__}'")
-    return value
+@dataclasses.dataclass
+class IndexSourceConfig:
+    mode: t.Literal["copy", "concat"]
+    filenames: list[str]
+
+    @classmethod
+    def _load(cls, data: dict[str, t.Any]) -> t.Self:
+        if "copy" in data:
+            return cls(mode="copy", filenames=[data["copy"]])
+        elif "concat" in data:
+            return cls(mode="concat", filenames=[data["concat"]["files"]])
+        else:
+            _abort("Unexpected error: index_source did not have copy or concat")
 
 
 def _abort(message: str) -> t.NoReturn:

support/doc_config_schema.json

@@ -0,0 +1,80 @@
+{
+  "title": ".doc_config.yaml Validation Schema",
+  "description": "This schema describes the shape of our internal doc configs. It is used to validate configs so that the build script doesn't need to do this checking.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "title": {
+      "type": "string"
+    },
+    "short_description": {
+      "type": "string"
+    },
+    "example_dir": {
+      "type": "string"
+    },
+    "index_source": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/index_source_copy"
+        },
+        {
+          "$ref": "#/$defs/index_source_concat"
+        }
+      ]
+    },
+    "append_source_blocks": {
+      "type": "boolean"
+    },
+    "menu_weight": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "title",
+    "short_description",
+    "example_dir",
+    "index_source",
+    "append_source_blocks",
+    "menu_weight"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "index_source_copy": {
+      "type": "object",
+      "properties": {
+        "copy": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "copy"
+      ],
+      "additionalProperties": false
+    },
+    "index_source_concat": {
+      "type": "object",
+      "properties": {
+        "concat": {
+          "type": "object",
+          "properties": {
+            "files": {
+              "$ref": "#/$defs/string_array",
+              "minItems": 1
+            }
+          },
+          "required": [
+            "files"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "string_array": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

transfer_examples/move/.doc_config.yaml

@@ -8,7 +8,8 @@ short_description: |
     be copied to the destination and then deleted from the source.
 
 example_dir: 'move_flow'
-readme_is_index: true
+index_source:
+  copy: "README.adoc"
 append_source_blocks: true
 
 menu_weight: 100

transfer_examples/transfer_after_approval/.doc_config.yaml

@@ -5,7 +5,8 @@ short_description: |
     destination Guest Collection.
 
 example_dir: 'transfer_after_approval'
-readme_is_index: true
+index_source:
+  copy: "README.adoc"
 append_source_blocks: true
 
 menu_weight: 300

transfer_examples/two_hop/.doc_config.yaml

@@ -5,7 +5,8 @@ short_description: |
     destination. Remove from intermediate after completion.
 
 example_dir: 'two_hop'
-readme_is_index: true
+index_source:
+  copy: "README.adoc"
 append_source_blocks: true
 
 menu_weight: 200