Refactor lapis.md API docs generation to be on-demand and non-destructive #169

New issue

Closed

opened 2026-05-31 18:23:31 +00:00 by steve · 0 comments

steve commented

2026-05-31 18:23:31 +00:00

Owner

Problem

The lapis.md package currently runs API-doc generation automatically in dev, build, and astro check. The generator deletes the published src/content/docs/developers/api-reference/ tree up front, rebuilds into a temp location, and then copies results back. That is heavier than necessary for normal site work and makes the published docs tree vulnerable to deletion when generation fails mid-run.

Goal

Make API-doc regeneration explicit, keep generated docs checked into the repo, preserve the published docs tree on failures, and add a non-mutating freshness check for package validation and CI.

Scope

Update @lapis-notes/lapis.md scripts so only api-docs:generate mutates tracked API docs.
Refactor the TypeDoc postprocessing script to generate into temp output, support write/check modes, and sync atomically into the tracked docs tree only after success.
Add tests covering frontmatter injection, class-doc path rewrites, drift detection, stale-file removal on successful sync, and failure preservation.
Update package and rendered specs to document the new manual generation and validation behavior.

Non-goals

Moving generated API docs out of the repo.
Auto-regeneration during site dev, build, or check.
Changing the published API surface or Astro sidebar structure beyond what the pipeline requires.

Acceptance Criteria

pnpm --filter @lapis-notes/lapis.md api-docs:generate is the only command that rewrites src/content/docs/developers/api-reference/.
Site dev, build, and check:astro do not regenerate tracked API docs implicitly.
A non-mutating api-docs:check command fails when committed docs drift from the generated output and passes when they match.
Generator failures leave the existing committed API docs tree intact.
Successful regeneration removes stale generated files that no longer exist in the latest API output.
Package/local spec docs describe that API reference pages are checked in, regenerated manually, and freshness-checked during validation.

Implementation Notes

Prefer a shared implementation that:

runs TypeDoc into an untracked temp directory,
rewrites/annotates markdown in temp output,
compares temp output against the tracked docs tree,
applies writes/removals only after successful generation,
reports concise path-level drift in check mode.

Suggested Files or Specs To Inspect

packages/lapis.md/package.json
packages/lapis.md/scripts/postprocess-api-docs.mjs
packages/lapis.md/typedoc.json
packages/lapis.md/spec.md
spec/src/20-packages/lapis.md/index.md
turbo.json

Validation Commands

pnpm --filter @lapis-notes/lapis.md check:all
pnpm --filter @lapis-notes/lapis.md test
make spec-lint
mdbook build spec

#94 Capture live app screenshots for public docs

Follow-up Tasks

Fix the backlog helper/title collision around placeholder-titled issue #147 separately; backlog:new required --force to create this issue.

Implementation Summary

Made lapis.md API docs generation explicit, non-destructive, drift-checked, and covered by package-local tests and spec updates.

Refactor the lapis.md TypeDoc pipeline so committed API reference pages remain durable site content, regeneration happens only when explicitly requested, and validation checks drift without mutating tracked files. ## Problem The lapis.md package currently runs API-doc generation automatically in `dev`, `build`, and `astro check`. The generator deletes the published `src/content/docs/developers/api-reference/` tree up front, rebuilds into a temp location, and then copies results back. That is heavier than necessary for normal site work and makes the published docs tree vulnerable to deletion when generation fails mid-run. ## Goal Make API-doc regeneration explicit, keep generated docs checked into the repo, preserve the published docs tree on failures, and add a non-mutating freshness check for package validation and CI. ## Scope - Update `@lapis-notes/lapis.md` scripts so only `api-docs:generate` mutates tracked API docs. - Refactor the TypeDoc postprocessing script to generate into temp output, support write/check modes, and sync atomically into the tracked docs tree only after success. - Add tests covering frontmatter injection, class-doc path rewrites, drift detection, stale-file removal on successful sync, and failure preservation. - Update package and rendered specs to document the new manual generation and validation behavior. ## Non-goals - Moving generated API docs out of the repo. - Auto-regeneration during site `dev`, `build`, or `check`. - Changing the published API surface or Astro sidebar structure beyond what the pipeline requires. ## Acceptance Criteria - `pnpm --filter @lapis-notes/lapis.md api-docs:generate` is the only command that rewrites `src/content/docs/developers/api-reference/`. - Site `dev`, `build`, and `check:astro` do not regenerate tracked API docs implicitly. - A non-mutating `api-docs:check` command fails when committed docs drift from the generated output and passes when they match. - Generator failures leave the existing committed API docs tree intact. - Successful regeneration removes stale generated files that no longer exist in the latest API output. - Package/local spec docs describe that API reference pages are checked in, regenerated manually, and freshness-checked during validation. ## Implementation Notes Prefer a shared implementation that: - runs TypeDoc into an untracked temp directory, - rewrites/annotates markdown in temp output, - compares temp output against the tracked docs tree, - applies writes/removals only after successful generation, - reports concise path-level drift in check mode. ## Suggested Files or Specs To Inspect - `packages/lapis.md/package.json` - `packages/lapis.md/scripts/postprocess-api-docs.mjs` - `packages/lapis.md/typedoc.json` - `packages/lapis.md/spec.md` - `spec/src/20-packages/lapis.md/index.md` - `turbo.json` ## Validation Commands - `pnpm --filter @lapis-notes/lapis.md check:all` - `pnpm --filter @lapis-notes/lapis.md test` - `make spec-lint` - `mdbook build spec` ## Related Issues - `#94` Capture live app screenshots for public docs ## Follow-up Tasks - Fix the backlog helper/title collision around placeholder-titled issue `#147` separately; `backlog:new` required `--force` to create this issue. ## Implementation Summary Made lapis.md API docs generation explicit, non-destructive, drift-checked, and covered by package-local tests and spec updates.

steve

2026-05-31 18:23:31 +00:00