Skip to content

docs: Diátaxis documentation overhaul (compile-verified)#840

Draft
QuitHub wants to merge 1 commit into
typelevel:mainfrom
QuitHub:docs/diataxis-overhaul
Draft

docs: Diátaxis documentation overhaul (compile-verified)#840
QuitHub wants to merge 1 commit into
typelevel:mainfrom
QuitHub:docs/diataxis-overhaul

Conversation

@QuitHub

@QuitHub QuitHub commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Radically expand and restructure the documentation (Diátaxis)

The published docs were 4 tutorial pages. This PR turns them into a full
Diátaxis documentation set — 45 pages across
Getting Started, Tutorials, How-to guides, Concepts and Reference — and fixes
the broken tutorial/intro.md stub.

What's new

  • Getting Started: overview, installation, 5-minute quick start.
  • Tutorials: the in-memory (Star Wars) and DB-backed (World) tutorials,
    revised with cross-links and a corrected schema; plus a new mutations &
    subscriptions
    tutorial.
  • 14 how-to guides: filtering/ordering/paging, composing mappings, SQL
    backends, interfaces/unions, jsonb, custom scalars/enums, schema & query
    directives, effects/batching, errors, mapping validation, generic
    derivation, circe, serving over HTTP.
  • 9 concept pages: architecture (compiler → algebra → interpreter),
    mappings & cursors, elaboration, schema model, nullability, effects,
    composition, introspection.
  • 14 reference pages: schema/SDL, mapping types, query algebra, predicates,
    Result/Problem, cursor, context/env, elaboration phases, and the SQL/circe/
    generic backends.

Compile-verified

Every example is real, compiled code. Most are snipped from existing demo and
test mappings via the existing Output.snip mechanism — those sources gained
comment-only // #tag markers (no behaviour change). Three tiny in-memory
example mappings live in modules/docs; the docs module now depends on
core/circe/generic so those and the inline mdoc blocks compile.

sbt docs/tlSite builds clean (mdoc compilation + Laika strict internal-link
validation), and sbt rootJVM/Test/compile confirms the tagged sources still
compile.

Notes for reviewers

  • Code-bearing example sources: modules/docs/src/main/scala/grackle/*.scala.
  • All other example code is snipped verbatim from demo/ and modules/*/test.
  • No library/runtime code changed; the only src/main edits are comment tags.

Restructure the documentation from 4 tutorial pages into a full
Diátaxis information architecture: Getting Started, Tutorials, How-to
guides, Concepts, and Reference (45 pages).

Highlights:
- Getting Started: overview, install, and a 5-minute quick start.
- Tutorials: existing in-memory (Star Wars) and DB-backed (World)
  tutorials revised with cross-links; new mutations & subscriptions
  tutorial.
- 14 how-to guides: filtering/ordering/paging, composing mappings,
  SQL backends, interfaces/unions, jsonb, custom scalars/enums,
  schema & query directives, effects/batching, errors, validation,
  generic derivation, circe, and serving over HTTP.
- 9 concept pages explaining the compiler/algebra/interpreter
  architecture, mappings & cursors, elaboration, the schema model,
  nullability, effects, composition and introspection.
- 14 reference pages covering schemas/SDL, the mapping catalog, the
  query algebra, predicates, Result/Problem, the SQL/circe/generic
  backends and running operations.

All code examples are compile-verified. Most are snipped from real
compiled sources (demo + test mappings) via the existing
`Output.snip` mechanism — sources are tagged with comment-only
`// #tag` markers. Three small in-memory example mappings live in
modules/docs (the docs module now depends on core/circe/generic so
they and the inline `mdoc` blocks compile). The whole site builds
clean with `sbt docs/tlSite` (mdoc + Laika strict link validation).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@milessabin milessabin marked this pull request as draft June 17, 2026 09:55
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