| 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 |