Commit Graph
9 Commits
Author SHA1 Message Date
LGUG2Z 91463ff033 refactor(docgen): remove HTML output, focus exclusively on MDX generation
BREAKING CHANGE: HTML output format has been removed. The tool now
generates MDX documentation for Astro Starlight exclusively.

This commit removes the HTML generator and all associated code,
simplifying the codebase to focus on MDX output only.

Removed

- `src/generator.rs` - HTML documentation generator (1827 lines)
- `src/identifiers.rs` - CSS/HTML identifiers (371 lines)
- `src/templates/base.html` - HTML base template
- `src/templates/macros.html` - HTML macro templates
- `src/templates/style.css` - CSS styles (1216 lines)
- `src/templates/test_index.html` - Test HTML template
- `build.rs` - CSS minification build script
- `tests/json_schema_test_suite.rs` - JSON Schema test suite (501 lines)
- `tests/fixtures/json-schema-test-suite/` - All draft2020-12 test fixtures

Removed Dependencies

- lightningcss (CSS minification)
- rayon (parallel processing)
- struct_iterable (struct iteration)
- regex, chrono (dev dependencies)

Added

- `ENUMS.md` - Comprehensive documentation of all 11 Rust enum patterns
  and their JSONSchema representations
- 12 unit tests covering all enum patterns to prevent Value duplication

Changed

CLI (src/main.rs)
- Remove `--format` flag (was html/mdx, now mdx only)
- Remove `Format` enum
- Simplify to always output MDX

Library (src/lib.rs)
- Remove `Options` struct and `generate_html()` function
- Remove `Generator`, `CSS`, `IDS`, `TYPE_CLASSES` exports
- Update module docs to reflect MDX-only output
- Update tests to use `generate_mdx()`

Templates (src/templates/mdx_macros.md)
- Add section headers organizing macros by function
- Add comprehensive comments documenting all enum patterns
- Fix duplicate Value rendering for const variants
- Add Pattern 7 detection for externally tagged enums
- Change `<details>` to `<details open>` for better visibility
- Render required properties before optional ones
- Move `$ref` handling after `type` in render_type_badge (Pattern 6 fix)

Preparation (src/prepare.rs)
- Minor formatting improvements
2025-12-27 20:32:20 -08:00
LGUG2Z f48586033d feat(docgen): improve mdx output with linked defaults and markdown support
- Add default value linking: when a default value refers to an enum
  variant, it now links to the type definition (e.g., "Monitor" links
  to CrossBoundaryBehaviour type)
- Make mdx_escape code-block aware: braces inside fenced code blocks
  (```) and inline code (`) are no longer escaped, preserving proper
  JSON code block rendering in descriptions
- Use raw markdown descriptions in MDX templates instead of converting
  to HTML then stripping tags, which was destroying code blocks
- Skip redundant type badge for documented const variants in MDX output
2025-12-26 15:07:48 -08:00
LGUG2Z 855f6b2592 build(nix): add flake and devshell 2025-12-24 14:26:55 -08:00
LGUG2Z 6bf0975898 test(jsonschema): add index.html for test suite outputs
Add functionality to generate an index.html file after running the
JSON Schema Test Suite integration tests, providing easy navigation
of generated documentation.

Features:
- Use Tera template (test_index.html) for consistent styling
- Display statistics: total schemas, test files, with/without content
- Annotate each schema with content status (has properties/$defs or not)
- Show JSON Schema features/keywords used in each test schema
- Include build information: git commit hash, dirty status, timestamps
- Group schemas by source test file for easy navigation
2025-12-22 10:23:12 -08:00
LGUG2Z 2e3913c325 test(jsonschema): add json schema test suite compat tests
Add comprehensive integration tests using the official JSON-Schema-Test-Suite
draft2020-12 examples to ensure the CLI handles all valid JSON Schema constructs
without crashing.

Changes:
- Add 80 fixture files from JSON-Schema-Test-Suite draft2020-12
- Add parallelized integration test that runs CLI against all 448 schemas
- Normalize non-standard $ref patterns (root refs, JSON pointers, external URIs)
- Decode URL-encoded and JSON pointer escaped characters in $ref paths
- Embed type usages directly in $defs to avoid Tera lookup issues with
  special characters in definition names
- Handle missing $defs gracefully in template rendering

The test suite runs in ~5 seconds using Rayon for parallel execution.
2025-12-22 10:04:47 -08:00
LGUG2Z 25b4a8fae9 feat(docgen): add build-time css validation
Implement compile-time validation that all CSS class names defined in
identifiers.rs have corresponding styles in style.css.

Build Script Integration:
- Add build.rs with lightningcss for CSS parsing
- Parse style.css and extract all class selectors
- Iterate over CssClasses and TypeClasses using struct_iterable
- Fail build if any defined class lacks CSS rules

Runtime Test (backup validation):
- Add `test_all_css_classes_are_styled` in identifiers.rs
- Uses regex to extract class names from CSS file
- Verifies both CSS and TYPE_CLASSES are fully styled
- Allows dynamic prefixes like "depth-" that are generated at runtime

Struct Changes:
- Add `#[derive(Iterable)]` to CssClasses and TypeClasses
- Add `#[allow(dead_code)]` to IDS and HtmlIds (used by main, not build)

Cleanup:
- Remove unused CSS classes: `map_entries`, `too_deep`
- Remove corresponding entries from identifiers.rs

New Dependencies:
- lightningcss = "1.0.0-alpha.68" (build-dependency)
- struct_iterable = "0.1" (dependency and build-dependency)
- serde with derive (build-dependency for struct_iterable)

This ensures CSS/Rust synchronization is maintained and catches
missing styles before runtime.
2025-12-22 09:44:02 -08:00
LGUG2Z ff0088e293 chore(deps): cargo update and remove unused dev-dependencies
Dependency Updates:
- Upgrade pulldown-cmark from 0.12 to 0.13
- Simplify version specifiers (e.g., "1.1" → "1", "1.19" → "1")

Removed Dependencies:
- Remove pretty_assertions dev-dependency (unused)
- Remove diff transitive dependency
- Remove yansi transitive dependency

Cargo.toml Changes:
- schemars: "1.1" → "1"
- serde: "1.0" → "1"
- serde_json: "1.0" → "1"
- tera: "1.19" → "1"
- pulldown-cmark: "0.12" → "0.13"
- Remove pretty_assertions = "1.4"
2025-12-22 09:31:29 -08:00
LGUG2Z 7d4b7857bb feat(docgen): add wrapper type detection and improved tuple/float display
Implement intelligent detection of "wrapper types" (anyOf patterns with map
variant and inner type) to render them more meaningfully in documentation.

Wrapper Type Detection:
- Detect anyOf patterns like `[{object with additionalProperties: T}, T]`
- Mark detected wrappers with `_wrapper_type` and `_wrapper_inner` metadata
- Display inner type directly instead of showing misleading "enum" badge
- Link wrapper types to their inner type definitions
- Add `_display_name` field for wrapper types with numeric suffixes

Float Display Improvements:
- Display "float" instead of "number" for JSON Schema number types in tuples
- Use `type-float` CSS class for consistent styling
- Homogeneous tuples now show as "float; N" for number arrays

Navigation Enhancements:
- Build navigation from prepared schema (includes wrapper display names)
- Add `display_names` map to template context for type name resolution
- Track type usages for "Usages" section in definitions

Test Coverage:
- Add comprehensive tests for wrapper type rendering
- Test tuple float/integer display formatting
- Verify wrapper types don't show "Enum variants" dropdown
- Test non-wrapper anyOf still correctly shows enum badge
2025-12-22 09:31:29 -08:00
LGUG2Z c85edf242f feat(docgen): initial implementation of html doc generator
Implement a complete Rust library and CLI tool for generating self-contained
HTML documentation from schemars::Schema (JSON Schema) objects.

Core Features:
- Library API with `generate_html()` function and `Options` struct
- CLI binary accepting JSON Schema input files with optional title override
- Tera-based HTML templating with base template and reusable macros
- Markdown rendering for schema descriptions via pulldown-cmark
- Dark/light theme support following system preferences
- Searchable properties with instant search functionality
- Collapsible nested structures for complex schemas
- Responsive design for mobile, tablet, and desktop

Library Components:
- `generator.rs`: Main HTML generation logic with Tera template engine
- `prepare.rs`: Schema preprocessing for template rendering (1667 lines)
- `lib.rs`: Public API with SchemaExt trait for typed schema accessors
- `main.rs`: CLI interface using clap for argument parsing

Template System:
- `base.html`: Main HTML structure with header, sidebar, and content areas
- `macros.html`: Reusable Tera macros for rendering schema components
- `style.css`: Complete CSS with CSS variables for theming (955 lines)
2025-12-22 09:31:19 -08:00