How this manual is built

Public graph

Created about 4 hours ago, updated about 4 hours ago · Owners: Root

ID29552

The files. Each page is a Markdown file in docs/dna, with front matter: key, title, parents (all equal), kind (overview, concept, technical or guide), a one-sentence summary, order among its siblings, and covers, the code it describes. Pages link each other with [text](dna:key) and show images with ![Caption](media/name.webp). A page that moves or goes is listed in docs/dna/_moved.yml.

Sync on deploy. Every deploy runs bin/rails dna:sync as Root (Dna::Sync). It creates new pages first, then renders and updates every page: links become node links, images get a version in their address so readers always see the current one, and each page ends with its generated navigation (Read on, Under the hood, Step by step, and Part of when it has several parents). A page whose file is gone is retired: its open Talk topics and anything readers added under it go to its successor, and its address redirects. Changes are recorded as Root's versions, so every page has a history like any other node.

Diagrams from code. Each diagram is a short Ruby file in docs/dna/media/src, placing nodes, spaces and edges in the style of the graph view, with frames to step through (Dna::Diagram). bin/rails dna:diagrams draws them as SVG; several frames play as an animation, with no scripts.

Screenshots from demo data. bin/rails dna:screens builds its own database with the demo people, graphs and proposals (db/seeds/development/manual.seeds.rb), starts the app on it, and walks headless Chrome through the entries of docs/dna/media/screens.yml: pictures become WebP, sequences of frames become GIFs. Your own data is never used, so the pictures show the same story every time.

Checks. bin/rails dna:lint (Dna::Lint) applies the rules of Writing this manual, and the test suite runs it on every pull request: too many children, a guide without a picture, a missing summary, a broken link, an image without a caption, a diagram out of date with its source, or a covers path that names no file fail the build. bin/rails dna:check (Dna::Check, no database) runs on every pull request too: it compares the branch with its base, and for each changed file that pages cover, wants one of those pages changed. It names the screenshots on those pages to retake, and warns about user-facing code (controllers, views, helpers, policies, services, models, serializers, scripts and routes) that no page covers yet.

See in the graph Search below

Parents1More general nodes this one belongs to