mirror of
https://github.com/Effect-TS/effect.git
synced 2026-11-22 03:25:35 +08:00
DOCKER.md is the guide to effect/docker: setup, configuration and discovery, the services, streams and handles, registry credentials, API versions, errors, tracing, DockerApi as the contract, and testing your own code against a fake Engine built from DockerApi with HttpApiBuilder. Its examples type-check, and the ones that run were run against Docker 29. ai-docs gains "Working with Docker", a sandbox service that pulls an image and runs commands in a container its layer cleans up; LLMS.md is regenerated. The module docs of DockerApi, DockerConfig and DockerVolumes gain an example, DockerImages.buildStream its typical reasons, and DockerEngine records why sanitizeCause stays after #9855: HttpClientError's own serialization redacts only the query names known where it is serialized, and keeps the full request as a property.
AI docs
LLMS.md is generated from ai-docs/src.
Add content
- Add or update markdown in
ai-docs/src/**/index.mdfor section intro text. - Add examples as
.tsfiles in the same folder. - Run
pnpm ai-docgento regenerateLLMS.md.
Source file conventions
- Use numeric filename prefixes to control ordering (
10_,20_, etc). Avoid starting with0unless explicity requested to do so. - Use a top JSDoc block with
@titleand optional description to control rendered title/description. fixturesdirectories are ignored and not included in the generated documentation. Use them for any supporting code or data needed for examples.
Example guidelines
Before writing an example, look at the existing examples in ai-docs/src to
learn the style and conventions used in this project. Also read the current
LLMS.md to understand the content and style of the documentation.
All code examples should be well commented explaining the how and why of the code, not just what the code is doing. The goal is to teach users how to use the API.
Code must represent real world usage and best practices. Do not include toy examples that are not representative of how the API should be used in practice.
- Prefer using the service style of structuring code, as this represents real world usage and best practices.
- Use the
fixturesdirectory to illustrate / suggest best practices for project structure, file organization, and code organization.
Pull requests with only ai documentation changes DO NOT need a changeset.
Regeneration
- One-shot:
pnpm ai-docgen - Watch mode:
pnpm ai-docgen:watch
pnpm ai-docgen regenerates LLMS.md files from content in ai-docs/src.