Debian Codegraph @

.claude/skills/doc-site/SKILL.md

raw
1 # Documentation Site
2
3 Hugo-based documentation site for testify, auto-generated from source code.
4
5 ## Running locally
6
7 ```bash
8 # 1. Generate docs from source
9 go generate ./...
10
11 # 2. Start Hugo dev server
12 cd hack/doc-site/hugo
13 ./gendoc.sh
14
15 # Visit http://localhost:1313/testify/
16 # Auto-reloads on changes to docs/doc-site/
17 ```
18
19 ## Site structure
20
21 ```
22 hack/doc-site/hugo/
23 hugo.yaml # Main Hugo config
24 metrics.yaml # Generated metrics (codegen output, merged into site params)
25 testify.yaml # Version info + build metadata
26 gendoc.sh # Dev server launcher
27 layouts/ # Custom layout overrides
28 themes/hugo-relearn/ # Relearn documentation theme
29
30 docs/doc-site/ # Content (mounted by Hugo)
31 api/ # Generated: domain pages, index, metrics (DO NOT EDIT)
32 usage/ # Hand-written: USAGE, GENERICS, CHANGES, MIGRATION, etc.
33 project/ # Hand-written: APPROACH, maintainer docs
34 ```
35
36 ## Generated vs hand-written content
37
38 | Path | Generated? | Notes |
39 |------|-----------|-------|
40 | `docs/doc-site/api/*.md` | Yes | Domain pages, index, metrics. Regenerate with `go generate` |
41 | `docs/doc-site/api/metrics.md` | Yes | Quick index table + API counts |
42 | `docs/doc-site/usage/*.md` | No | Hand-written guides |
43 | `docs/doc-site/project/*.md` | No | Hand-written project docs |
44
45 ## Dynamic counts via Hugo params
46
47 Function and assertion counts are generated into `metrics.yaml` and merged
48 into Hugo's `site.Params.metrics`. Use the relearn `siteparam` shortcode
49 to reference them in hand-written markdown:
50
51 ```markdown
52 We have {{% siteparam "metrics.assertions" %}} assertions across
53 {{% siteparam "metrics.domains" %}} domains.
54 ```
55
56 Available params: `metrics.domains`, `metrics.functions`, `metrics.assertions`,
57 `metrics.generics`, `metrics.nongeneric_assertions`, `metrics.helpers`, `metrics.others`.
58
59 Per-domain: `metrics.by_domain.<slug>.count`, `metrics.by_domain.<slug>.name`.
60
61 Hugo math functions (`sub`, `mul`, `add`) are NOT available in markdown content.
62 For computed values, add them to the codegen `buildMetrics()` in
63 `codegen/internal/generator/doc_generator.go`.
64
65 ## Adding a new hand-written page
66
67 1. Create `docs/doc-site/<section>/<FILE>.md` with Hugo front matter
68 2. Set `weight:` to control ordering in the sidebar
69 3. Use relearn shortcodes: `{{% notice %}}`, `{{% expand %}}`, `{{< tabs >}}`, etc.
70 4. Reference API counts with `{{% siteparam "metrics.<key>" %}}`
71
72 ## Relearn theme features used
73
74 - `{{% notice style="info" %}}` -- callout boxes
75 - `{{% expand title="..." %}}` -- collapsible sections
76 - `{{< tabs >}}` / `{{% tab %}}` -- tabbed content
77 - `{{< cards >}}` / `{{% card %}}` -- side-by-side cards
78 - `{{% icon icon="star" color=orange %}}` -- inline icons
79 - `{{% siteparam "key" %}}` -- site param substitution
80 - `{{< mermaid >}}` -- diagrams