Artifact [3b7e28d99d]

Artifact 3b7e28d99df346b189b085cb029ec9b430ea28cca65f64d49af9d399981b5ef2:

• File Makefile — part of check-in [f30849a466] at 2026-04-26 14:14:53 on branch trunk — docs: usability improvements from DX audit (#9)

  Implements all seven recommended changes from the docs audit:

  1. SDK pages now show package names in nav. Add scripts/prepend-sdk-frontmatter.sh that prepends '--- title: <pkg> ---' to each gomarkdoc-generated api.md; wired into 'make docs-gen-sdk'. Sidebar previously showed five undifferentiated 'API' entries; now shows cli, db, dst, libfossil, observer/otel.

  2. /examples/ populated with paragraphs + GitHub deep-links for embed-repo-api and wasm. No longer a placeholder pointing back at the repo.

  3. Architecture page gets an inline SVG mirroring the landing-page diagram. Self-contained CSS (uses currentColor + ember accent) so it tracks Hextra's light/dark theme without depending on the landing's CSS scope.

  4. Cross-links added: quickstart -> production + extension-points, migration -> architecture, architecture -> extension-points. Extension Points and Production patterns are now reachable via prose, not just the sidebar.

  5. /docs/ landing expanded from 3 sentences to a 7-line subsection map calling out each page's purpose.

  6. Version indicator in navbar (libfossil v0.4.2). Override layouts/_partials/navbar-title.html mimics Hextra's default and appends a small mono version tag from .Site.Params.version.

  7. New /docs/production/ page covering error handling, context cancellation, telemetry wiring, repo-handle lifetime, and driver selection — the patterns the quickstart's log.Fatal shortcuts gloss over. (user: [email protected], size: 1648) [annotate] [blame] [check-ins using]

GOMARKDOC_VERSION := v1.1.0

.PHONY: test test-drivers test-otel test-all vet build setup-hooks docs-gen-sdk docs-gen-llms docs-serve docs-build docs

test:
	go test ./... -count=1 -timeout=120s

test-drivers:
	@echo "=== modernc (default) ==="
	go test ./... -count=1 -timeout=120s
	@echo "=== ncruces ==="
	go test -tags test_ncruces ./... -count=1 -timeout=120s
	@echo "=== all drivers passed ==="

test-otel:
	cd observer/otel && GOWORK=off go test ./... -count=1

test-all: test-drivers test-otel build
	@echo "=== all targets passed ==="

vet:
	go vet ./...

build:
	go build ./cmd/libfossil/

setup-hooks:
	git config core.hooksPath .githooks
	@echo "Pre-commit hook installed. Runs both drivers + DST + OTel (~45s) before each commit."
	@echo "Skip with: git commit --no-verify"

docs-gen-sdk:
	@command -v gomarkdoc >/dev/null 2>&1 || go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@$(GOMARKDOC_VERSION)
	gomarkdoc --output docs/site/content/docs/reference/sdk/libfossil/api.md     ./
	gomarkdoc --output docs/site/content/docs/reference/sdk/cli/api.md           ./cli/
	gomarkdoc --output docs/site/content/docs/reference/sdk/db/api.md            ./db/
	gomarkdoc --output docs/site/content/docs/reference/sdk/observer/otel/api.md ./observer/otel/
	gomarkdoc --output docs/site/content/docs/reference/sdk/dst/api.md           ./dst/
	bash scripts/prepend-sdk-frontmatter.sh

docs-gen-llms: docs-gen-sdk
	bash scripts/gen-llms-txt.sh

docs-serve:
	cd docs/site && hugo server -D --port 1313

docs-build: docs-gen-sdk docs-gen-llms
	cd docs/site && hugo --minify

docs: docs-build
	@echo "=== docs: built into docs/site/public/ ==="