# Demeter Library API Docs (TypeDoc)

The Demeter domain libraries under `libs/demeter/*` are documented with
[TypeDoc](https://typedoc.org), which turns their exported TypeScript types and
TSDoc comments into a browsable API reference.

## Setup

Each library has its own `typedoc.json` pointing at its public entry point
(`src/index.ts`) and its own `tsconfig.lib.json`:

```jsonc
{
  "entryPoints": ["src/index.ts"],
  "tsconfig": "tsconfig.lib.json",
  "out": "docs",
  "name": "@demeter/<lib>",
  "excludePrivate": true,
  "excludeInternal": true,
  "excludeExternals": true,
}
```

> **Why per-library, not one unified config?** A single TypeDoc run that points
> at `tsconfig.base.json` pulls the _entire_ monorepo (every domain's path
> mappings) into one TypeScript program and exhausts the heap (OOMs at 9 GB).
> Scoping each run to one library's `tsconfig.lib.json` keeps the program small
> and fast.

## Covered libraries (14)

`core`, `analytics`, `automation`, `community`, `hydroponics`, `intelligence`,
`inventory`, `journal`, `planner`, `plants`, `preservation`, `sensors`, `tasks`,
`weather`.

## Generating

For a single library:

```bash
cd libs/demeter/<lib> && npx typedoc          # output → libs/demeter/<lib>/docs/
```

For all of them (from the repo root):

```bash
for d in libs/demeter/*/typedoc.json; do
  ( cd "$(dirname "$d")" && npx typedoc )
done
```

The generated HTML lands in each library's `docs/` directory, which is
**git-ignored** (`libs/demeter/*/docs/`) — the configs are the source of truth;
the HTML is a build artifact regenerated on demand or in CI.

## Quality

- Reports are generated with `excludePrivate` / `excludeInternal` so only the
  intended public surface is documented.
- TypeDoc's `validation.invalidLink` is on, so broken `{@link}` references are
  surfaced as warnings.
- All 14 configs were verified to generate with **0 errors** against the current
  source.

For the REST API (as opposed to the libraries), see the OpenAPI-based
[API reference](api/README.md).
