Skip to content

chore - add Prismplane docs site and strict docs CI (#9)#98

Draft
dannymeijer wants to merge 35 commits into
mainfrom
feature/9-docs-ci
Draft

chore - add Prismplane docs site and strict docs CI (#9)#98
dannymeijer wants to merge 35 commits into
mainfrom
feature/9-docs-ci

Conversation

@dannymeijer

@dannymeijer dannymeijer commented Jul 8, 2026

Copy link
Copy Markdown
Member

Summary

This PR turns the existing IncQL documentation into a strict MkDocs Material site and completes the screenshot-annotated Prismplane landing page. The homepage now explains IncQL as a typed data-logic plane through a distinct physical Prism visual, accessible syntax-surface examples, and a clearer path from authoring to inspection and execution.

Closes #9.

Deployment note: this remains a draft. It does not publish the unfinished site to production; Pages continues to deploy from main only after merge.

Type of change

  • Bug fix
  • New feature
  • Refactor / maintenance
  • Documentation
  • CI / tooling
  • RFC (adds/updates docs/rfcs/*)

Area(s)

Select the primary areas touched (labels sync from checked lines when the triage workflow runs):

  • Package & tests
  • Specification (RFCs)
  • Documentation
  • Automation & repo config
  • Other

Key details

  • User-facing behavior: adds a responsive IncQL launch page with an explicit IncQL/Prism identity distinction, a purpose-built process-flow scene, engine icons, a smaller semantic-model bridge, and five keyboard-accessible authoring-surface tabs showing equivalent Incan, SQL, DataFrame, LazyFrame, and pipeline examples.
  • Internals: moves the tab behavior into docs/javascripts/prismplane.js, loads it through MkDocs, adds local Material-style SVG assets, replaces the previous process-flow raster variants with process-flow-stage-v3.png, and preserves a readable progressive-enhancement fallback when JavaScript is unavailable.
  • CI and docs platform: adds the Material documentation configuration, navigation, strict documentation checks, link checking, accessibility smoke checks, and the Pages workflow already developed on this branch.
  • Risks: the homepage uses custom HTML, CSS, and JavaScript inside MkDocs. Strict builds, responsive browser QA, keyboard checks, progressive-enhancement checks, and the existing package/consumer gates cover the main regression paths.

Testing / verification

  • make ci (or make fmt-check, make build, make test)
  • Manual verification described below

Manual verification notes:

  • make ci: formatting, test-style, vocab-companion tests, 216 registry checks, library build, and 269 IncQL tests passed. Its final public-consumer target initially encountered sandboxed DNS; make smoke-consumer then passed with crates.io access.
  • mkdocs build --strict -d /tmp/incql-site-publish
  • node --check docs/javascripts/prismplane.js
  • git diff --check and git diff --cached --check
  • Browser QA at desktop, tablet, and mobile widths: no horizontal overflow; clean console; all five tabs switch examples by click and keyboard; active-tab semantics and no-JavaScript fallback verified; Prism artwork and engine icons remain legible responsively.

Docs impact

  • No docs changes needed
  • Docs updated
  • Docs follow Divio intent (tutorial/how-to/reference/explanation) where applicable

If docs updated:

  • Link(s): docs/index.md, mkdocs.yml, docs/stylesheets/prismplane.css, docs/javascripts/prismplane.js

Checklist

  • I kept public docs user-focused and moved internals to contributing docs when appropriate
  • I avoided duplicating canonical install/run instructions in multiple places
  • I added/updated tests where it materially reduces regressions

@incan-triage-bot incan-triage-bot Bot added automation CI, Makefile, .github/, repo config documentation Improvements or additions to documentation labels Jul 8, 2026
@dannymeijer dannymeijer changed the title chore - add strict MkDocs docs CI (#9) chore - add Prismplane docs site and strict docs CI (#9) Jul 8, 2026
@dannymeijer dannymeijer added this to the InQL-v0.1 milestone Jul 11, 2026
@dannymeijer dannymeijer self-assigned this Jul 11, 2026
@github-project-automation github-project-automation Bot moved this to Todo in @IncQL Jul 11, 2026
# Conflicts:
#	README.md
#	docs/architecture.md
#	docs/docs_map.md
#	docs/language/reference/substrait/read_root_binding_contract.md
#	docs/release_notes/v0_1.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automation CI, Makefile, .github/, repo config documentation Improvements or additions to documentation

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

Add CI for documentation site (MkDocs strict build)

1 participant