phoenix-typescript-package-docs

# Phoenix TypeScript Package Docs Keep the curated TypeScript package docs aligned with the real npm package surface area and with the publish-time sync flow. ## Quick Reference | Task | What to inspect | What to update | | ----- | ----- | ----- | | Fix a stale example | `js/packages/<pkg>/src/` exports and function signatures | Canonical MDX under `docs/phoenix/sdk-api-reference/typescript/packages/<pkg>/` | | Add or remove a page | Existing package-doc folder and `docs.json` nav | Canonical MDX, `docs.json`, and any landing-page links | | Add a new package to the bundled-docs system | `js/scripts/sync-package-docs.mjs` and package `package.json` | Sync map, package `files`, package `prepack`, and Mintlify nav | | Verify publish output | `node js/scripts/sync-package-docs.mjs` and `npm pack --dry-run` | Generated `js/packages/<pkg>/docs/` contents and tarball entries | ## Source Of Truth The canonical authored docs live in Mintlify pages: ```text docs/phoenix/sdk-api-reference/typescript/packages/phoenix-client/ docs/phoenix/sdk-api-reference/typescript/packages/phoenix-evals/ docs/phoenix/sdk-api-reference/typescript/packages/phoenix-otel/ ``` The package examples remain in the package source trees: ```text js/packages/phoenix-client/examples/ js/packages/phoenix-evals/examples/ js/packages/phoenix-otel/examples/ ``` The published npm docs are staged copies: ```text js/packages/phoenix-client/docs/ js/packages/phoenix-evals/docs/ js/packages/phoenix-otel/docs/ ``` Do not hand-edit `js/packages/*/docs/`. Treat those folders as generated publish artifacts. Ground doc content in the real package `src/` and `examples/` directories, but keep the published package docs focused on curated MDX pages. ## Current Packaging Flow These files define the bundled-docs workflow: - `js/scripts/sync-package-docs.mjs` - `js/packages/phoenix-client/package.json` - `js/packages/phoenix-evals/package.json` - `js/packages/phoenix-otel/package.json` - `docs.json` - `docs/phoenix/sdk-api-reference/typescript/overview.mdx` - `docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-client.mdx` - `docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-evals.mdx` - `docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-otel.mdx` Each supported package must have: - a canonical Mintlify package-doc folder - a `docs` entry in `files` - a `prepack` hook that runs the sync script for that package - a `postpublish` hook that removes staged package docs (not `postpack` — `pnpm publish` stats the package files after the pack lifecycle, so a `postpack` clean deletes them mid-publish and fails with ENOENT) - visible navigation in `docs.json` ## Authoring Rules ### 1. Read code before editing docs Always ground docs in the actual exported surface: - root exports: `js/packages/<pkg>/src/index.ts` - submodule exports: `js/packages/<pkg>/src/<module>/index.ts` - implementation and parameter shapes: matching files in `src/**` - real usage patterns: `js/packages/<pkg>/examples/**` Do not infer argument names or object shapes from older docs. Confirm them from code first. ### 2. Document exported entrypoints, not internals Prefer pages and examples that match package entrypoints a developer imports: - `@arizeai/phoenix-client` - `@arizeai/phoenix-client/prompts` - `@arizeai/phoenix-client/spans` - `@arizeai/phoenix-client/sessions` - `@arizeai/phoenix-client/experiments` - `@arizeai/phoenix-evals` - `@arizeai/phoenix-evals/llm` - `@arizeai/phoenix-otel` Do not center docs around private helpers or internal-only module paths. ### 3. Keep the packaged docs flat Inside each package `docs/` folder, prefer a flat page layout such as: ```text overview.mdx experiments.mdx ``` Top-level authored MDX pages should stay flat. ### 4. Keep website docs and packaged docs aligned If you add, remove, or rename a package-doc page: 1. update the canonical MDX file 2. update `docs.json` 3. update any package landing page links that point into the package-doc section 4. rerun the sync script ### 5. Prefer examples that prove real shapes When a function takes a wrapped object such as `spanAnnotation`, `documentAnnotation`, `sessionAnnotation`, `spanNote`, `project`, or `dataset`, the example must use the real wrapper shape from code. Common failure mode: docs drift toward simplified pseudo-APIs that do not match actual exported parameter names. ### 6. Hide agent-only implementation context When a page benefits from implementation breadcrumbs like internal `src/**` paths or a full source map, do not render them as visible Markdown headings, bullet lists, or fenced code blocks in Mintlify. Use hidden semantic HTML instead: ```mdx <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files" > <h2>Relevant Source Files</h2> <ul> <li><code>src/example.ts</code> for the canonical implementation</li> </ul> </section> <section className="hidden" data-agent-context="source-map" aria-label="Source map" > <h2>Source Map</h2> <ul> <li><code>src/index.ts</code></li> <li><code>src/helpers.ts</code></li> </ul> </section> ``` Use semantic HTML elements like `<section>`, `<h2>`, `<ul>`, and `<li>` inside these hidden blocks rather than generic `<div>` wrappers, Markdown bullets, or fenced text blocks. Reserve this pattern for brief agent-only implementation context. Keep user-facing docs focused on API behavior, workflows, and runnable examples. Do not treat hidden blocks as access control. If content should be hidden from navigation as a whole, use a hidden page instead. ## Workflow ### Step 1: Determine the affected package and modules Inspect the code change or user request and map it to one or more packages: - `phoenix-client` - `phoenix-evals` - `phoenix-otel` Then inspect the corresponding `src/` exports before writing docs. ### Step 2: Update canonical Mintlify docs Edit only the canonical pages: ```text docs/phoenix/sdk-api-reference/typescript/packages/<pkg>/*.mdx ``` If the change affects high-level discovery, also update: - `docs/phoenix/sdk-api-reference/typescript/overview.mdx` - `docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-<pkg>.mdx` ### Step 3: Sync generated package docs Run: ```bash node js/scripts/sync-package-docs.mjs ``` Or for one package: ```bash node js/scripts/sync-package-docs.mjs phoenix-client node js/scripts/sync-package-docs.mjs phoenix-evals node js/scripts/sync-package-docs.mjs phoenix-otel ``` This stages: - canonical MDX pages into `js/packages/<pkg>/docs/` To remove staged docs manually: ```bash node js/scripts/sync-package-docs.mjs clean phoenix-client ``` ### Step 4: Verify the npm artifact From each affected package: ```bash cd js/packages/phoenix-client && npm pack --dry-run cd js/packages/phoenix-evals && npm pack --dry-run cd js/packages/phoenix-otel && npm pack --dry-run ``` Confirm the tarball includes: - `docs/*.mdx` - `src/**` ### Step 5: Check for nav and path regressions If you changed page names or package coverage: - confirm `docs.json` still parses - confirm every referenced package-doc page exists - confirm the package landing pages link to the correct section ## When Adding A New Bundled-Docs Package If Phoenix starts shipping package docs for another TypeScript package, update all of: 1. `docs/phoenix/sdk-api-reference/typescript/packages/<new-package>/` 2. `docs.json` 3. `js/scripts/sync-package-docs.mjs` 4. `js/packages/<new-package>/package.json` Required package manifest changes: - include `docs` in `files` - add a `prepack` hook that syncs the package docs ## Validation Checklist - [ ] Examples match actual exported argument shapes - [ ] Canonical docs were edited instead of generated package docs - [ ] `node js/scripts/sync-package-docs.mjs` succeeds - [ ] `npm pack --dry-run` includes `docs/*.mdx` - [ ] `docs.json` paths still resolve ## Anti-Patterns - Editing `js/packages/*/docs/` directly - Updating examples without checking `src/**` - Documenting internal helpers instead of importable entrypoints - Adding a package-doc page without wiring it into `docs.json` - Updating Mintlify docs but forgetting to verify the packed npm artifact