Skip to content

BUILD.md

Latest commit

 

History

History
43 lines (25 loc) · 4.36 KB

BUILD.md

File metadata and controls

43 lines (25 loc) · 4.36 KB
Raw

How the build works

php build.php runs these stages. Anything inconsistent fails the build; --lint lists the rest.

  1. Symbols (lib/Symbols.php): reflection and docblocks of the packages in symbols.php. Tags: DOCBLOCK-STANDARD.md.
  2. Pages: content/**.md, except content/<project>/topics/ (those are topic definitions). Front matter of prose pages: title, description, status, order, see_also, and for the Manual project: phasync|swerve, topic: slug, role: concept|guide.
  3. Model (lib/Model.php): topics, the Manual, the Index, breadcrumbs, previous/next, See also, examples. Written to build/model.json (shape: MODEL.md).
  4. Render (stage 1: the old templates, which ignore the model), links check, public/.

Files

File What
content/<project>/topics/<slug>.md A topic: front matter title, summary, order, status; the body is its Introduction. Projects: phasync (includes http-client), swerve.
topics-map.php 'Symbol' => 'slug', 'phasync::go' => 'coroutines': the decided topic tables (phasync.dev/TOPICS-DRAFT.md) for every symbol in them. Names as in @see. Where the source @topic disagrees, the map wins and lint reports it (topics-map.php), so the source can be fixed.

A symbol's topic

@topic slug in the source, else topics-map.php, else none (lint error unmapped). A source @topic that disagrees with the map is overridden by the map and reported. Lint lists the symbols served only by the map as untagged: those are what remains to tag in the source. A method of a facade class (phasync, Swerve\Swerve) is assigned on its own; any other method has its class's topic. The slug must be a topic of the symbol's project (unknown @topic).

See also

Per symbol: its own @see lines in author order, annotation else target summary; nothing added automatically. Lint prints one-way @see pairs as INFO (advisory); @see none on the target silences them. After See also, Used in lists guide/concept pages linking the symbol with [[Symbol]] or {@see}.

Examples

Every @example path caption file is run once, from the package root, as php -d display_errors=1 path with the docs repo's vendor/autoload.php prepended, 20 s timeout, stdout and stderr together; 8 at a time. Output, exit code and ok (exit 0, no timeout) go into the model. A failure or timeout is a lint error with the first lines of output. Fenced php blocks in docblocks are listed as inline examples and are not run. --skip-examples skips running (fast builds). The example files in the packages are never changed.

Lint

php build.php --lint prints, per package and for site (topics, map, pages): the problems and counts, then a summary. Exit code 1 when anything is wrong, except "no example" (advisory: hundreds, counted only). --lint --json prints {summary, problems[]}.

What stage 2 renders from model.json

The Manual page of each project and a page per topic (/topics/<project>/<slug>/: introduction, concept pages, guides, symbols with members, the topic's examples); the Index (symbols, members); on every symbol page: breadcrumbs, topic, Changelog (since and changed), Notes (notes, warnings), numbered examples with captions and captured output, See also with its source label; on every prose page: breadcrumbs, previous/next, See also; the search index from symbols and pages.

Sidebars, width, landing pages

The sidebar is the current sub-section's own tree (projects.<p>.sidebars in the model; MODEL.md). Get started: the numbered path, in front-matter order; the sub-navigation's "Get started" links to its first page (Render::startUrl). Manual: the topic books, drawn by Render::sidebar. Index (symbols, examples): All symbols, Classes, Functions (/<p>/symbols/classes/, /functions/: the same index, filtered by kind), Examples, and an A to Z row linking to the letter anchors. Changelog: Releases (one per ## heading) and the pages Upgrading, Planned changes, Development process, each only when its source exists in the package repo.

Width and breakpoints live in the kit's site.css (--maxw 1560px content; prose 72ch; rail hidden below 1200px). Landing pages and the 404 have no breadcrumb: Render::crumbs returns nothing for a trail of fewer than two items.

Renamed topic slugs are listed in Render::RENAMED_TOPICS; the old Manual URL gets a redirect stub.