Skip to content

feat(export): enhance ODCS HTML export - #1447

Open
GauthierCapouillez wants to merge 2 commits into
datacontract:mainfrom
GauthierCapouillez:enhance-html-export
Open

feat(export): enhance ODCS HTML export#1447
GauthierCapouillez wants to merge 2 commits into
datacontract:mainfrom
GauthierCapouillez:enhance-html-export

Conversation

@GauthierCapouillez

Copy link
Copy Markdown

Summary

The current ODCS HTML export is generated from a single monolithic Jinja2 template
(datacontract_odcs.html, ~688 lines). This PR introduces a complete overhaul:
the template is decomposed into focused, reusable partials and macros, the layout
is modernised to match the visual design of the datacontract-editor React app, and
semantic HTML markup issues are fixed.

Motivation

  • The monolithic template is hard to maintain, extend, and test.
  • HTML display fits to datacontract-editor display rules
  • Invalid <dt>/<dd> elements used outside a <dl> parent caused browsers to
    silently repair the DOM, breaking CSS space-y-* selectors and producing
    inconsistent vertical spacing between sections.

Changes

Architecture — Modular partials

datacontract_odcs.html is reduced to ~45 lines (assembler only).
All rendering logic is extracted into partials_odcs/:

Partial Renders
header.html Top navigation bar
title.html Contract title, status badges, YAML dialog trigger
fundamentals.html Core metadata (name, version, ID, owner, tags…)
term_of_use.html Description — purpose, usage, limitations
diagram.html Entity-relationship Mermaid diagram
schema.html Schema tables with nested properties
servers.html Server list with per-type icons
team.html Team contact card
support.html Support channels
roles.html Access roles
pricing.html Pricing information
sla.html SLA properties
custom_properties.html Custom properties (mapping or list formats)
dialog_yaml.html Full YAML modal dialog
footer.html Footer

Architecture — Reusable macros

  • macros/schema.html — recursive render_nested_properties with type tooltips, badges
  • macros/server.htmlserver_icon mapping 30+ server types to SVG icons
  • macros/support.html — support channel icon/link rendering
  • macros/authoritative_definitions.html — authoritative definition badges

Visual design

  • Card-based layout consistent with datacontract-editor
  • Consistent space-y-6 vertical rhythm between all sections
  • Responsive grids for properties
  • Colour-coded status badges (Draft, Active, Deprecated, …)
  • Server type icons (BigQuery, Databricks, Snowflake, Kafka, PostgreSQL, …)
  • Support channel icons (Slack, email, GitHub Issues, Jira, …)
  • Panzoom-enabled ERD diagram + YAML source modal

Bug fixes

  • Semantic markup: <dt>/<dd> outside <dl> replaced with <div> in
    team, term_of_use, roles, sla, servers — invalid usage caused silent
    browser DOM repair breaking space-y-* selectors.
  • Custom properties: migrated from <table> to <dl>/grid; supports both
    mapping and list input formats; break-all prevents horizontal overflow.

Testing

uv run pytest tests/ -k "html or export"129/129 pass.
Full suite (no Docker): 1080 pass, 0 regressions.

  • Tests pass (uv run pytest)
  • Code formatted (uv run ruff check --fix && uv run ruff format)
  • Docs updated (if relevant)
  • CHANGELOG.md entry added

@GauthierCapouillez

Copy link
Copy Markdown
Author

@simonharrer As requeted, I updated the html export to fit to datacontract-editor visualization

# Conflicts:
#	CHANGELOG.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant