1# AI docs
2
3`LLMS.md` is generated from `ai-docs/src`.
4
5## Add content
6
71. Add or update markdown in `ai-docs/src/**/index.md` for section intro text.
82. Add examples as `.ts` files in the same folder.
93. Run `pnpm ai-docgen` to regenerate `LLMS.md`.
10
11## Source file conventions
12
13- Use numeric filename prefixes to control ordering (`10_`, `20_`, etc). Avoid starting with `0` unless explicity requested to do so.
14- Use a top JSDoc block with `@title` and optional description to control rendered title/description.
15- `fixtures` directories are ignored and not included in the generated
16 documentation. Use them for any supporting code or data needed for examples.
17
18## Example guidelines
19
20Before writing an example, look at the existing examples in `ai-docs/src` to
21learn the style and conventions used in this project. Also read the current
22`LLMS.md` to understand the content and style of the documentation.
23
24**All code examples should be well commented** explaining the how and why of the
25code, not just what the code is doing. The goal is to teach users how to use the
26API.
27
28**Code must represent real world usage and best practices.**
29Do not include toy examples that are not representative of how the API should be
30used in practice.
31
32- **Prefer using the service style** of structuring code, as this represents real
33 world usage and best practices.
34- Use the `fixtures` directory to illustrate / suggest best practices for
35 project structure, file organization, and code organization.
36
37Pull requests with only ai documentation changes **DO NOT** need a changeset.
38
39## Regeneration
40
41- One-shot: `pnpm ai-docgen`
42- Watch mode: `pnpm ai-docgen:watch`
43
44`pnpm ai-docgen` regenerates `LLMS.md` files from content in `ai-docs/src`.