# Documentation page format

Contributor reference for the source files under `site/doc/`. This is not part of
the published API reference. It describes how contributors write and validate
those pages.

## Where the sources live

- `site/doc/source/api/*.txt` contains function pages.
- `site/doc/source/type/*.txt` contains type pages.
- `site/doc/source/handler/*.txt` contains handler pages.
- `site/doc/source/guide/*.txt` contains the numbered Learn Capy guides.
- `site/doc/source/how-to/*.txt` contains task-focused how-to articles.
- `site/doc/areas/*.txt` contains the page names for each group.

`scripts/generate_capy_docs.py` reads these and writes route modules under
`site/doc/content/`. Each route module prints its complete static detail HTML.
It also writes the index, all-pages, and search catalogs. Run it after editing
any page. The runtime loads the generated route modules.

`scripts/generate_capy_doc_signatures.py` writes
`site/doc/lib/capy_signatures.generated.h`.

## Directives

A directive starts a line with `:` and its body runs to the next directive.

| Directive | Purpose |
| --- | --- |
| `:title` | Display title, when it differs from the page name |
| `:sig` | The Capy signature, one per line for overloads |
| `:params` | One `name : description` per line |
| `:returns` | What the call evaluates to |
| `:errors` | Failure behaviour |
| `:content` | Prose, rendered as Markdown |
| `:example capy ENTRY [caption]` | A runnable example |
| `:output` | Expected output, following a render example |
| `:see` | Related page names, one per line |

`ENTRY` is one of `render`, `cli`, `component`, `init`, `once`, `ws`, `service`, or `task`.

`:content` may appear more than once. The generator joins the parts in order,
which lets prose sit between examples. Guide examples appear at their source
position. The generator does not add a second example section.

## Rules the gates enforce

`:sig` must match the signature `capyc` generates from `src/capy/stdlib.capy`.
Editing a signature by hand without changing the stdlib fails
`scripts/generate_capy_doc_signatures.py --check`.

API and how-to examples are handler **bodies**, except complete units with the `service` entry.
Service examples can declare unit state, named service handlers, and a `RENDER` preview.
Do not add handler wrappers to other API examples or redeclare `request`. Guide examples are complete units.

Examples may not reference host-language types or private `__bearer` APIs.

Every guide in `site/doc/source/guide/` needs one runnable render example with an exact
`:output` block. `scripts/test_capy_guide_examples.sh` runs each example with an approved output over HTTP and compares byte for byte. Generated guide navigation links to the adjacent guide.
The guide set is pinned in `CANONICAL_GUIDES` in
`scripts/check_capy_doc_examples.py`, so adding a guide means adding it there too.

API pages must document a public Capy function. Type and handler pages must
document the matching language form. Use a how-to page for task guidance that
does not document a callable API.

## Example style

Prefer inferred map literals, such as `var user := {email: "ada@example.test"}`, and member access for fixed identifier keys. Use member calls where natural, but keep the documented function clear. Show equivalent forms when they help explain the API. For example, `user.get("email")`, `get(user, "email")`, `user.email`, and `user["email"]` read the same value.

Keep conversions when types require them or the example teaches conversion or fallback behavior. Typed-array-to-`any` conversion is not redundant. Map literals already produce `any`, and coercive `print` arguments do not need an explicit `string()` conversion.

## Example outputs

Add `:output` immediately after a self-contained `:example capy render` when the result helps explain the code. The generator renders it as escaped plain text below the source. The output is an approved expectation, not a value computed during a page request.

Use fixed inputs. Do not capture current times, random values, private data, or machine-specific paths. State the request inputs for HTTP examples. For database, task, service, or external-provider examples, describe the effect unless a controlled fixture verifies it. Do not run those operations merely to populate documentation.

API output checks run with `python3 scripts/test_capy_api_outputs.py --verify`. Guide output checks run with `scripts/test_capy_guide_examples.sh`. Both use the local development server. A mismatch fails the check. Neither command replaces expected output. Review a changed result before updating its `:output` block. Expected output includes a final newline.

Code declarations and setup fragments do not need output blocks. Markdown examples in how-to pages need explicit request fixtures when their results depend on HTTP inputs.

## Adding a page

1. Write `site/doc/source/api/<function>.txt`, named after the public function.
2. Write task guidance in `site/doc/source/how-to/<slug>.txt`.
3. Add API capability evidence to `src/capy/parity_manifest.h`, and keep the array size correct.
4. Run `python3 scripts/generate_capy_docs.py`, then the doc gates.