comet-ml--opik/apps/opik-documentation/AGENTS.md

# Repository Guidelines

## Scope & Inheritance
- This file contains docs-module specifics only.
- Follow `../../AGENTS.md` for shared monorepo workflow, PR, and security policy.

## Project Structure & Module Organization
`apps/opik-documentation` contains two documentation pipelines:

- `documentation/` (primary Fern docs site)
  - `fern/docs/` for documentation pages and navigation content
  - `docs/cookbook/` for source Jupyter notebooks
  - `static/` and `fern/img/` for assets (use only `fern/img` for new images)
  - `update_cookbooks.sh` to regenerate cookbook markdown from notebooks
- `python-sdk-docs/` (Python SDK reference docs)
  - `source/` for `.rst` content
  - `Makefile` and `requirements.txt` for doc builds
- `README.md` is present in this folder; follow `documentation/fern/docs/contributing/*` for contribution process details and conventions.

## Build, Test, and Development Commands
See also `../../AGENTS.md#build-test-and-development-commands` for full monorepo commands.

- `cd documentation && npm install`
  - Install Fern docs dependencies (run once or after dependency updates).
- `cd documentation && npm run dev`
  - Run docs website locally with live reload.
- `cd documentation && ./update_cookbooks.sh`
  - Regenerates `fern/docs/cookbook/*.mdx` from `docs/cookbook/*.ipynb`.
- `cd python-sdk-docs && pip install -r requirements.txt`
  - Install Sphinx tooling for SDK references.
- `cd python-sdk-docs && make dev`
  - Serve Python SDK docs at `http://127.0.0.1:8000`.
- `cd python-sdk-docs && make build`
  - Generate static HTML into `python-sdk-docs/build/html`.

## Coding Style & Naming Conventions
- Write concise, user-oriented docs (avoid internal implementation detail unless needed).
- Use existing Markdown/MDX style in `documentation/fern/docs/**` and reStructuredText style in `python-sdk-docs/source/**`.
- Keep file names descriptive and kebab-case (`quickstart.mdx`, `api-reference.mdx`).
- Keep 2-space indentation in YAML/JSON snippets and frontmatter.
- Treat `documentation/fern/docs.yml` (or `docs.yaml` where used) as the routing source of truth; do not infer URL paths from folder layout alone.
- Store new images under `documentation/fern/img/`.

## Testing Guidelines
- There is no dedicated automated docs test suite in this directory.
- Validation is primarily local render verification:
  - run `npm run dev` for Fern pages,
  - run `make dev` for Sphinx reference docs.
- For generated artifacts (cookbooks/SDK docs), verify output in local preview before merging.

## Agent Contribution Workflow
- This module is part of the Opik monorepo; follow the shared workflow in `../../AGENTS.md#agent-contribution-workflow`.
- Run docs-local validation commands in this file before requesting review.

## Commit & Pull Request Guidelines
- Follow shared commit/PR policy in `../../AGENTS.md`.
- Docs-specific additions: include validation steps and screenshots for visible docs changes when relevant.

## Security & Configuration Tips
- Follow shared security policy in `../../AGENTS.md`.
- Docs-specific rule: use placeholders (`<API_KEY>`, `<TOKEN>`) and never publish real credentials in docs or notebooks.