docs: Diátaxis documentation overhaul (compile-verified)#840
Draft
QuitHub wants to merge 1 commit into
Draft
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdstub.What's new
revised with cross-links and a corrected schema; plus a new mutations &
subscriptions tutorial.
backends, interfaces/unions, jsonb, custom scalars/enums, schema & query
directives, effects/batching, errors, mapping validation, generic
derivation, circe, serving over HTTP.
mappings & cursors, elaboration, schema model, nullability, effects,
composition, introspection.
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.snipmechanism — those sources gainedcomment-only
// #tagmarkers (no behaviour change). Three tiny in-memoryexample mappings live in
modules/docs; the docs module now depends oncore/circe/genericso those and the inlinemdocblocks compile.sbt docs/tlSitebuilds clean (mdoc compilation + Laika strict internal-linkvalidation), and
sbt rootJVM/Test/compileconfirms the tagged sources stillcompile.
Notes for reviewers
modules/docs/src/main/scala/grackle/*.scala.demo/andmodules/*/test.src/mainedits are comment tags.