Address docs examples review

Author: koxudaxi

docs/llms-full.txt

@@ -29480,7 +29480,7 @@ components:
 ```
 <!-- END AUTO-GENERATED DOC EXAMPLE: openapi.read-only-write-only-allof.schema -->
 
-Generated `UserRequest` will exclude `created_at` (readOnly from Timestamps).
+Generated `UserRequest` will exclude `created_at`, `updated_at`, and `id` because they are readOnly fields from the flattened Timestamps/User schemas. Generated `UserResponse` will exclude `password` and `api_key` because they are writeOnly fields from Credentials.
 
 ### ⚠️ Collision Handling
 
@@ -31431,6 +31431,9 @@ models/
 `-- shared.py
 ```
 
+**models/__init__.py:**
+_No code beyond the generated header._
+
 **models/schema_a.py:**
 
 ```python

docs/model-reuse.md

@@ -129,6 +129,9 @@ models/
 `-- shared.py
 ```
 
+**models/__init__.py:**
+_No code beyond the generated header._
+
 **models/schema_a.py:**
 
 ```python

docs/openapi.md

@@ -421,7 +421,7 @@ components:
 ```
 <!-- END AUTO-GENERATED DOC EXAMPLE: openapi.read-only-write-only-allof.schema -->
 
-Generated `UserRequest` will exclude `created_at` (readOnly from Timestamps).
+Generated `UserRequest` will exclude `created_at`, `updated_at`, and `id` because they are readOnly fields from the flattened Timestamps/User schemas. Generated `UserResponse` will exclude `password` and `api_key` because they are writeOnly fields from Credentials.
 
 ### ⚠️ Collision Handling
 

scripts/build_docs_examples.py

@@ -23,8 +23,8 @@
 PYTHON_GENERATED_HEADER_PATTERN = re.compile(
     r"\A# generated by datamodel-codegen:\n"
     r"#   filename:  .+\n"
-    r"(?:#   timestamp:\s+.+\n)?"
-    r"\n",
+    r"(?:#   timestamp:\s+.+(?:\n|$))?"
+    r"\n?",
 )
 
 
@@ -63,10 +63,15 @@ def render_file_example(*, language: str, path: Path, strip_python_header: bool
     return fenced(language, content)
 
 
+def directory_files(path: Path) -> list[Path]:
+    """Return stable file entries for generated directory examples."""
+    return sorted(file for file in path.iterdir() if file.is_file())
+
+
 def directory_tree(path: Path, *, root_name: str) -> str:
     """Render a stable text tree for generated directory examples."""
     lines = [f"{root_name}/"]
-    files = sorted(file for file in path.iterdir() if file.is_file())
+    files = directory_files(path)
     for index, file in enumerate(files):
         branch = "`--" if index == len(files) - 1 else "|--"
         lines.append(f"{branch} {file.name}")
@@ -81,14 +86,35 @@ def render_reuse_scope_tree_example() -> str:
         "**Output with `--reuse-scope tree`:**",
         fenced("text", directory_tree(output_path, root_name="models")),
     ]
-    for file_name in ("schema_a.py", "schema_b.py", "shared.py"):
+    for file in directory_files(output_path):
+        content = read_python_output(file)
         lines.extend((
-            f"**models/{file_name}:**",
-            fenced("python", read_python_output(output_path / file_name)),
+            f"**models/{file.name}:**",
+            fenced("python", content) if content.strip() else "_No code beyond the generated header._\n",
         ))
     return "\n".join(lines)
 
 
+def _file_example(
+    example_id: str,
+    doc: str,
+    *,
+    language: str,
+    path: Path,
+    strip_python_header: bool = False,
+) -> DocsExample:
+    """Build a docs example from one fixture file."""
+    return DocsExample(
+        example_id=example_id,
+        path=DOCS / doc,
+        render=lambda: render_file_example(
+            language=language,
+            path=path,
+            strip_python_header=strip_python_header,
+        ),
+    )
+
+
 def docs_examples() -> tuple[DocsExample, ...]:
     """Return all generated docs example sections."""
     return (
@@ -97,70 +123,56 @@ def docs_examples() -> tuple[DocsExample, ...]:
             path=DOCS / "openapi.md",
             render=lambda: details("api.yaml", "yaml", read_text(TEST_DATA / "openapi" / "api.yaml")),
         ),
-        DocsExample(
-            example_id="openapi.quick-start.output",
-            path=DOCS / "openapi.md",
-            render=lambda: render_file_example(
-                language="python",
-                path=EXPECTED_MAIN / "openapi" / "general.py",
-                strip_python_header=True,
-            ),
+        _file_example(
+            "openapi.quick-start.output",
+            "openapi.md",
+            language="python",
+            path=EXPECTED_MAIN / "openapi" / "general.py",
+            strip_python_header=True,
         ),
-        DocsExample(
-            example_id="openapi.read-only-write-only.schema",
-            path=DOCS / "openapi.md",
-            render=lambda: render_file_example(
-                language="yaml",
-                path=TEST_DATA / "openapi" / "read_only_write_only.yaml",
-            ),
+        _file_example(
+            "openapi.read-only-write-only.schema",
+            "openapi.md",
+            language="yaml",
+            path=TEST_DATA / "openapi" / "read_only_write_only.yaml",
         ),
-        DocsExample(
-            example_id="openapi.read-only-write-only.output",
-            path=DOCS / "openapi.md",
-            render=lambda: render_file_example(
-                language="python",
-                path=EXPECTED_MAIN / "openapi" / "read_only_write_only_all.py",
-                strip_python_header=True,
-            ),
+        _file_example(
+            "openapi.read-only-write-only.output",
+            "openapi.md",
+            language="python",
+            path=EXPECTED_MAIN / "openapi" / "read_only_write_only_all.py",
+            strip_python_header=True,
         ),
-        DocsExample(
-            example_id="openapi.read-only-write-only-allof.schema",
-            path=DOCS / "openapi.md",
-            render=lambda: render_file_example(
-                language="yaml",
-                path=TEST_DATA / "openapi" / "read_only_write_only_allof.yaml",
-            ),
+        _file_example(
+            "openapi.read-only-write-only-allof.schema",
+            "openapi.md",
+            language="yaml",
+            path=TEST_DATA / "openapi" / "read_only_write_only_allof.yaml",
         ),
-        DocsExample(
-            example_id="model-reuse.reuse-model.output",
-            path=DOCS / "model-reuse.md",
-            render=lambda: render_file_example(
-                language="python",
-                path=EXPECTED_MAIN / "jsonschema" / "json_reuse_enum.py",
-                strip_python_header=True,
-            ),
+        _file_example(
+            "model-reuse.reuse-model.output",
+            "model-reuse.md",
+            language="python",
+            path=EXPECTED_MAIN / "jsonschema" / "json_reuse_enum.py",
+            strip_python_header=True,
         ),
         DocsExample(
             example_id="model-reuse.reuse-scope-tree.output",
             path=DOCS / "model-reuse.md",
             render=render_reuse_scope_tree_example,
         ),
-        DocsExample(
-            example_id="model-reuse.use-type-alias.schema",
-            path=DOCS / "model-reuse.md",
-            render=lambda: render_file_example(
-                language="json",
-                path=TEST_DATA / "jsonschema" / "reduce_duplicate_field_types.json",
-            ),
+        _file_example(
+            "model-reuse.use-type-alias.schema",
+            "model-reuse.md",
+            language="json",
+            path=TEST_DATA / "jsonschema" / "reduce_duplicate_field_types.json",
         ),
-        DocsExample(
-            example_id="model-reuse.use-type-alias.output",
-            path=DOCS / "model-reuse.md",
-            render=lambda: render_file_example(
-                language="python",
-                path=EXPECTED_MAIN / "jsonschema" / "reduce_duplicate_field_types.py",
-                strip_python_header=True,
-            ),
+        _file_example(
+            "model-reuse.use-type-alias.output",
+            "model-reuse.md",
+            language="python",
+            path=EXPECTED_MAIN / "jsonschema" / "reduce_duplicate_field_types.py",
+            strip_python_header=True,
         ),
     )
 
@@ -189,25 +201,37 @@ def iter_examples_by_path() -> Iterable[tuple[Path, tuple[DocsExample, ...]]]:
 
 def update_docs_examples(*, check: bool = False) -> int:
     """Update or check generated documentation examples."""
-    changed_paths = []
+    changed_content_by_path = {}
+    out_of_date_paths = []
+    missing_markers = False
     for path, examples in iter_examples_by_path():
         content = path.read_text(encoding="utf-8")
         updated_content = content
+        missing_marker_for_path = False
         for example in examples:
             updated_content, found = replace_example(updated_content, example)
             if not found:
-                return 1
+                missing_markers = True
+                missing_marker_for_path = True
+        if missing_marker_for_path:
+            continue
         if updated_content == content:
             continue
         if check:
-            print(f"Docs examples are out of date: {path}", file=sys.stderr)
-            print("Run 'python scripts/build_docs_examples.py' to update.", file=sys.stderr)
-            return 1
-        path.write_text(updated_content, encoding="utf-8")
-        changed_paths.append(path)
-
-    if changed_paths:
-        for path in changed_paths:
+            out_of_date_paths.append(path)
+            continue
+        changed_content_by_path[path] = updated_content
+
+    for path in out_of_date_paths:
+        print(f"Docs examples are out of date: {path}", file=sys.stderr)
+    if out_of_date_paths:
+        print("Run 'python scripts/build_docs_examples.py' to update.", file=sys.stderr)
+    if missing_markers or out_of_date_paths:
+        return 1
+
+    if changed_content_by_path:
+        for path, updated_content in changed_content_by_path.items():
+            path.write_text(updated_content, encoding="utf-8")
             print(f"Updated {path}")
         return 0
 

tests/data/expected/docs_examples/docs_example_render_helpers.txt

@@ -0,0 +1,17 @@
+
+<details>
+<summary>schema.yaml</summary>
+
+```yaml
+name: User
+```
+</details>
+
+```yaml
+name: User
+```
+
+```python
+class User:
+    pass
+```

tests/data/expected/docs_examples/main_check_up_to_date.txt

@@ -0,0 +1,4 @@
+return=0
+stdout:
+Docs examples are up to date.
+stderr:

tests/data/expected/docs_examples/reuse_scope_tree_example.txt

@@ -9,6 +9,9 @@ models/
 `-- shared.py
 ```
 
+**models/__init__.py:**
+_No code beyond the generated header._
+
 **models/schema_a.py:**
 
 ```python

tests/data/expected/docs_examples/update_docs_examples_check_problems.txt

@@ -0,0 +1,7 @@
+return=1
+stdout:
+stderr:
+Warning: markers not found for example.missing in <tmp>/missing.md
+Docs examples are out of date: <tmp>/outdated-one.md
+Docs examples are out of date: <tmp>/outdated-two.md
+Run 'python scripts/build_docs_examples.py' to update.

tests/data/expected/docs_examples/update_docs_examples_write_mode.txt

@@ -0,0 +1,10 @@
+return=0
+stdout:
+Updated <tmp>/doc.md
+stderr:
+content:
+Before
+<!-- BEGIN AUTO-GENERATED DOC EXAMPLE: example.write -->
+new
+<!-- END AUTO-GENERATED DOC EXAMPLE: example.write -->
+After