[CaffeinatedCoder]

Closes #115

Problem

You could only read the consumer docs as Markdown on GitHub. That meant no menu beyond the README's Documentation table, no search across the 16 guides and 7 package READMEs, and no API reference outside an IDE.

Change

• .github/workflows/docs.yml builds the site with DocFX and deploys it to GitHub Pages on a push to main only. main is the released state, so the site always shows the version dotnet add package installs. A pull request into main or release/** that touches what a page is built from builds the site with --warningsAsErrors and publishes nothing.

• site/ holds the setup:

  • docfx.json lists the content (docs/*.md, README.md, src/*/README.md, CHANGELOG.md) and the API metadata of the five run-time packages, read from one publish folder.
  • toc.yml is the menu: Home, Guides in the README's order, Reference (the package READMEs), API, Changelog.
  • template/conceptual.extension.js does the link rewrite described below.

• DocFX 2.81.0 is pinned in .config/dotnet-tools.json.

• The sources are not copied or edited. A link to a repository file that is not a page (design/, CONTRIBUTING.md, AGENTS.md, SECURITY.md, LICENSE) is added to the build as a resource, so DocFX still checks the file exists. The template then rewrites it, at build time, to https://github.com/.../blob/<built commit>/.... The workflow deletes the resource copies from the output. A build without --metadata _commit=<sha> fails with a message saying what to pass.

• One page edit: the README's directory link spikes/ became https://github.com/CaffeinatedCoder/CodoMetis.TypeKit/tree/main/spikes. DocFX can't check a directory link; DocumentationLinkTests checks the absolute address.

• Spike: DocFX lists the members of C# 14 extension blocks. Each one appears as an extension method on its static class and under "Extension Methods" on the type it extends, with its XML docs. The gaps, recorded in the decision:

  • Signatures are shown in their lowered form.
  • Members whose constraints the open type doesn't meet (OrDefault, OrNull) appear only on Option's page.
  • The one static block member, New(), shows as GuidValueExtensions.New<TSelf>().

  So the API pages ship. A workflow step fails if Option<T>'s or Result<T, TError>'s page stops listing its extension Select.

• CI lanes: site/** joins the prose class in tools/CiLanes, because the docs workflow and the conventions tests read it and nothing is built from it. ProseReaderTests now counts a "site" literal as prose. The new workflow stays "unlisted" like every other workflow (decision 113). The SelectionTests rows cover the new paths.

• DocsSiteTests (conventions, prose suite) holds:

  • the menu's Guides to the README's Documentation table, in order;
  • the menu's Reference to every shipping package's README;
  • the API metadata to every run-time package, with Analyzers and Generators exempt, each with a reason.

• Docs: decision record 0116, a README paragraph linking the site, a changelog line, and a CONTRIBUTING section on how the site is published and how a second line (/2.x/, /3.x/) would be added.

• No claim in test/oracles/ changes: the site adds no public member, and the new README sentence promises nothing about the library's API.

GitHub Pages is configured: Source is "GitHub Actions" (the API reports build_type: workflow, https://caffeinatedcoder.github.io/CodoMetis.TypeKit/). The first live deploy happens when the 2.3.0 release merges into main; the README and changelog links to the site go live then.

ADR number: the record is 0116; #136 merged 0115 into release/2.3.0 first, and this branch has merged it.

Tests

• Link check, seeded locally: three seeds each failed dotnet docfx site/docfx.json --warningsAsErrors (exit 255); without them the build reports 0 warnings:
  • a link to a missing page (InvalidFileLink);
  • a link to a missing heading of a page (InvalidBookmark);
  • a link to a missing design record (InvalidFileLink, through the resources).
• Link check, seeded in CI: 8dfe0a9 seeded a link to a missing page; the Docs check failed on it with InvalidFileLink ... no-such-page.md, exit 255. 546ac9c removed it.
• Rendered site: served locally. The menu renders, the design links open on GitHub at the commit, and search finds both guides and API pages (e.g. "materializer").
• CiLanes: 93 tests pass. Seeding site/** back out of the prose class fails the 3 new rows.
• DocsSiteTests / ProseReaderTests: 17 tests pass. Seeding a guide dropped from toc.yml, a package dropped from docfx.json, and "site" dropped from the prose detection fails one test each.
• Conventions classes affected (DocumentationLink, ReadmeSample, DesignRecord, Changelog, ReleaseWiring, CiLane, CiWithoutAi, PortableFileName, ShellScript): 1,461 pass. Oracles tests: 27 pass. DocsQuery tests: 106 pass.

🤖 Generated with Claude Code