[NA] [DOCS] docs: remove the v1 documentation version - #7946
Conversation
Serve only the Opik 2 docs. The v1 content surface, the version YAML files and the dead v1_noindex.js are gone, and docs.yml now carries the navigation directly instead of a versions list. Every published v1 URL is mapped onto its Opik 2 equivalent, using the canonical-url each v1 page already declared, with page-level targets where a matching page exists. The unversioned Opik 1 paths get the same treatment because they return 404 today, and seven existing redirects that pointed at those dead paths are repointed at their final pages. update_cookbooks.sh only ever generated pages into the v1 tree, so it goes too; the Opik 2 cookbook pages are maintained by hand. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The changelog pages carried /v1/ links from when they were copied over, and the READMEs linked both /v1/ paths and pre-2.0 paths. Both now name the Opik 2 page directly, so no reader takes a redirect hop. Two generators wrote into the removed v1 tree. The optimizer API reference now regenerates the Opik 2 page, and the template keeps the project-scoping note that page carries, so a run no longer deletes it. The cookbook banner matches the Opik 2 optimizer notebook slug, which restores its Colab button. Touching generate_fern_docs.py brings it under the optimizer mypy hook for the first time. The hook environment does not install opik_optimizer, so the two imports of it carry an inline ignore with that reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
github-actions
Bot
added
documentation
⏱️ pre-commit per-hook timing
⏭️ 24 skipped (no matching files changed)
|
|
🌿 Preview your docs: https://opik-preview-01a02510-799b-72d5-9fd8-ccf5b86230e1.docs.buildwithfern.com/docs/opik No broken links found Unverified links (timeout / rate-limited / server error — not failing the check)• https://aistudio.google.com/apikey (401) 📌 Results for commit b9161d0 |
Python SDK Unit Tests Results (Python 3.14)4 460 tests ±0 4 458 ✅ ±0 1m 56s ⏱️ ±0s Results for commit fb14b5b. ± Comparison against base commit 4537964. This pull request removes 1 and adds 1 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
![baz-reviewer[bot]](https://avatars.githubusercontent.com/in/933528?s=60&v=4){kind=small}
| - page: Optimizer introduction | ||
| icon: fa-regular fa-book | ||
| path: ./docs-v2/development/optimization-runs/quickstart_notebook.mdx | ||
| slug: optimizer_introduction_cookbook |
There was a problem hiding this comment.
Duplicate optimizer notebook navigation entry
The new Cookbooks & Tutorials registration points Optimizer introduction to the same quickstart_notebook.mdx as Quickstart notebook, so two routes expose one page as separate tutorials — should we keep one canonical registration, redirecting any legacy slug, or add a distinct MDX source?
Want Baz to fix this for you? Activate Fixer
| - source: "/docs/opik/v1/agent_optimization/:slug*" | ||
| destination: "/docs/opik/development/optimization-runs/:slug*" | ||
| permanent: true |
There was a problem hiding this comment.
Published optimizer URLs resolve to 404s
The /v1/agent_optimization/:slug* wildcard carries obsolete suffixes into /development/optimization-runs/, so renamed v1 pages resolve to nonexistent Opik 2 URLs while the explicit redirects cover only unversioned paths — should we add /v1/agent_optimization exceptions before the wildcard, mirroring the canonical mappings?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs.yml around lines 1652-1654, the
`/v1/agent_optimization/:slug*` wildcard preserves obsolete suffixes that have no
corresponding Opik 2 pages. Add explicit `/v1/agent_optimization` redirect exceptions
for the renamed or moved optimizer pages (including `opik_optimizer/quickstart`,
`opik_optimizer/models`, `best_practices/prompt_engineering`, and
`algorithms/hierarchical_reflective_optimizer`) before the wildcard, mirroring the
canonical mappings used by the existing unversioned redirects. Keep the wildcard only as
the fallback for suffixes that genuinely remain valid.
| / "docs-v2" | ||
| / "development" | ||
| / "optimization-runs" | ||
| / "advanced" | ||
| / "api_reference.mdx" |
There was a problem hiding this comment.
Generated API page violates frontmatter contract
The --write template emits title and subtitle but not headline, so fern check passes while each regeneration leaves the active docs-v2 api_reference.mdx noncompliant with .agents/skills/write-docs/SKILL.md — should we add headline to the template and align the checked-in generated page?
Want Baz to fix this for you? Activate Fixer You can also update your AI coding guidelines based on this comment by apply pr to [branch name]
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
sdks/opik_optimizer/scripts/generate_fern_docs.py around lines 491-495, update the
`main` generation flow and its static MDX template so the frontmatter includes both
`title` and the required `headline` field. Ensure the checked-in
`apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/advanced/api_reference.mdx`
is regenerated or updated to match, preserving the active docs-v2 target.
There was a problem hiding this comment.
Commit fb14b5b addressed this comment by adding the required headline field to both the generation template and the checked-in docs-v2 API page.
| ### 3. Make Your Changes | ||
| Update content primarily in: | ||
| - `fern/docs/`: Main markdown content (like this page). | ||
| - `/docs/cookbook`: Our collection of cookbooks and examples - Please note that you should not be updating the `cookbook` markdown files directly as they are generated from the Jupyter Notebook. | ||
| - `fern/docs-v2/`: Main markdown content (like this page). | ||
| - `/docs/cookbook`: Our collection of source Jupyter Notebooks for the cookbook pages. | ||
|
|
||
| Refer to the `docs.yml` file for the overall structure and navigation. |
There was a problem hiding this comment.
Notebook edits leave published cookbooks stale
Notebook-only changes to /docs/cookbook never reach the published cookbook because Fern publishes separate fern/docs-v2/**/*.mdx pages such as evaluation/evaluate_hallucination_metric.mdx, while the notebook workflow only runs tests — should we document manual MDX synchronization or add a supported conversion step?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
`apps/opik-documentation/documentation/fern/docs-v2/contributing/guides/documentation.mdx`
around lines 50-55, revise the “Make Your Changes” guidance so it does not imply
that updating `/docs/cookbook` alone publishes cookbook documentation. Explain that
notebooks are the source for cookbook examples/tests, while the corresponding
`fern/docs-v2/**/*.mdx` page must also be updated manually and kept synchronized, or
document a supported notebook-to-MDX conversion step if one exists.
There was a problem hiding this comment.
Commit fb14b5b addressed this comment by documenting that notebook changes are not converted automatically and requiring the matching MDX page to be updated in the same PR.
| - Introduced a `Opik.search_spans` method to search for spans in a project. See the [Search spans](/v1/tracing/export_data#exporting-spans) guide for more details. | ||
| - Released a new integration with [AWS Bedrock](/v1/integrations/bedrock) for using Opik with Bedrock models. | ||
| - Introduced the `Prompt` object in the SDK to manage prompts stored in the library. See the [Prompt Management](/development/prompt-library/getting-started) guide for more details. | ||
| - Introduced a `Opik.search_spans` method to search for spans in a project. See the [Search spans](/tracing/advanced/export-data#exporting-spans) guide for more details. |
There was a problem hiding this comment.
Grammatical error in SDK changelog
The article a before Opik.search_spans is grammatically incorrect; should we use “an Opik.search_spans method” or “the new Opik.search_spans method”?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
`apps/opik-documentation/documentation/fern/docs-v2/changelog/2024-11-04.mdx` around
lines 11-11, fix the SDK changelog sentence describing `Opik.search_spans`. Change the
article before the method name from “a” to “an” so it reads “an
`Opik.search_spans` method,” without altering the rest of the entry.
There was a problem hiding this comment.
Commit fb14b5b addressed this comment by changing “a” to “an” before Opik.search_spans in the changelog entry.
| </Frame> | ||
|
|
||
| Links to official docs: [Evaluating traces with images](/v1/production/rules#evaluating-traces-with-images) and [Using images in the Plaground](/v1/prompt_engineering/playground#using-images-in-the-playground) | ||
| Links to official docs: [Evaluating traces with images](/production/online-evaluation/rules#evaluating-traces-with-images) and [Using images in the Plaground](/development/prompt-playground#using-images-in-the-playground) |
There was a problem hiding this comment.
The link label says "Plaground" instead of "Playground" — should we fix the typo?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
apps/opik-documentation/documentation/fern/docs-v2/changelog/2025-10-21.mdx around line
37, correct the "Using images in the Plaground" link label so "Plaground" is spelled
"Playground." Keep the existing destination URL and surrounding changelog content
unchanged.
There was a problem hiding this comment.
Commit fb14b5b addressed this comment by correcting “Plaground” to “Playground” in the link label.
…history Review flagged the agent_optimization wildcard, and probing production proved it right in a way the comment did not describe. Obsolete unversioned optimizer paths resolve today through Fern's own moved-slug history rather than docs.yml: /agent_optimization/opik_optimizer/models reaches /development/optimization-runs/optimization/configure_models, and six siblings behave the same way. A wildcard on that prefix matches them first and carries the obsolete suffix across, turning each working redirect into a 404. The unversioned block is now explicit sources only, no wildcards, generated from the same map: 84 entries, each one a path that returns 404 on production today. Anything not listed keeps the behaviour it has now. The /v1/ wildcards stay, since every obsolete /v1/ path already 404s and the wildcard covers the 36 real pages. Also from review: the generated optimizer API reference gained the headline frontmatter field the docs convention requires, the contributing guide no longer implies notebook edits publish themselves now that nothing converts them, and two typos on changelog lines this branch already rewrote are fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
| - Introduced a `Opik.search_spans` method to search for spans in a project. See the [Search spans](/v1/tracing/export_data#exporting-spans) guide for more details. | ||
| - Released a new integration with [AWS Bedrock](/v1/integrations/bedrock) for using Opik with Bedrock models. | ||
| - Introduced the `Prompt` object in the SDK to manage prompts stored in the library. See the [Prompt Management](/development/prompt-library/getting-started) guide for more details. | ||
| - Introduced an `Opik.search_spans` method to search for spans in a project. See the [Search spans](/tracing/advanced/export-data#exporting-spans) guide for more details. |
There was a problem hiding this comment.
Search spans deep link misses section
The changelog link uses /tracing/advanced/export-data#exporting-spans, but the destination only emits #spans, so Fern opens the page top instead of the spans section — should we change the fragment to #spans or add an explicit exporting-spans anchor?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
`apps/opik-documentation/documentation/fern/docs-v2/changelog/2024-11-04.mdx` around
line 11, fix the Search spans changelog link so its URL fragment matches the destination
page’s existing `Spans` heading. Replace the invalid `#exporting-spans` fragment with
`#spans` so readers are taken directly to the relevant section.
There was a problem hiding this comment.
Commit 0919ac4 addressed this comment by changing the link fragment from #exporting-spans to #spans, matching the destination heading.
| </Frame> | ||
|
|
||
| Links to official docs: [Evaluating traces with images](/v1/production/rules#evaluating-traces-with-images) and [Using images in the Plaground](/v1/prompt_engineering/playground#using-images-in-the-playground) | ||
| Links to official docs: [Evaluating traces with images](/production/online-evaluation/rules#evaluating-traces-with-images) and [Using images in the Playground](/development/prompt-playground#using-images-in-the-playground) |
There was a problem hiding this comment.
Playground image deep link fails
The release note links to /development/prompt-playground#using-images-in-the-playground, but prompt_engineering/playground.mdx has no matching anchor or image-support section, so the published link opens the general Playground page instead of image guidance — should we add that section/anchor or retarget the link?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
`apps/opik-documentation/documentation/fern/docs-v2/changelog/2025-10-21.mdx` around
lines 37-37, fix the Playground image documentation link because its fragment does not
exist on the routed v2 page. Add a `using-images-in-the-playground` section and matching
anchor with the relevant image-usage instructions to
`prompt_engineering/playground.mdx`; if those instructions belong elsewhere, instead
update this link to an existing v2 page and valid fragment that specifically documents
Playground image support.
Rewriting the /v1/ links kept each fragment, but six of those sections no longer exist under the Opik 2 headings, so the links opened the page top instead of the section. Two were flagged in review; a sweep of every root-relative fragment in docs-v2 found the other four. Renamed sections now point at the real anchor (#spans, #using-configuration-files) or the nearest section that carries the content. Where Opik 2 dropped the material entirely — image support in the playground, the JS/TS section of the log-traces page — the fragment is gone and the link opens the page. The sweep also showed Fern slugifies heading anchors GitHub style, dropping punctuation rather than replacing it, which is why #trainvalidation-splits and #using-comet-debugger-mode-uibrowser are correct as they stand. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 participant
Details
Serve only the Opik 2 docs. The v1 content surface (
fern/docs/, 326 MDX files), both version YAML files and the never-wiredv1_noindex.jsare removed, anddocs.ymlnow carriestabs:/navigation:directly instead of aversions:list. The risk in a change like this is SEO, so every published v1 URL is mapped onto its Opik 2 equivalent rather than left to 404.canonical-urlin its frontmatter, so those curated targets are the base. Where a page-level equivalent exists the map prefers it over a section-level canonical (all 36/agent_optimization/*pages keep their tail under/development/optimization-runs/*). Two stale canonicals were corrected by hand. All 258 published v1 pages are mapped; none falls back to a generic target that a real page could serve./v1/...and/latest/...; 53 for the unversioned Opik 1 paths; 7 existing entries repointed because they pointed at pages that 404 today (/playground,/library/prompt_management,/cookbook/quickstart_notebook,/tracing/debug_modeand friends). The bare/v1and/latestprefixes need their own entries — Fern does not substitute an empty:slug*match into the destination, so they would otherwise resolve to the literal text/docs/opik/:slug*.changelog/2026-08-17.mdxexisted only in v1 and is ported todocs-v2/. Without it that entry and its URL would be lost.docs-v2changelog pages carried/v1/links from when they were copied over, and the READMEs linked both/v1/and pre-2.0 paths. All now name the Opik 2 page directly, so no reader takes a redirect hop.generate_fern_docs.pywrote the optimizer API reference only into the v1 tree; it now regenerates the Opik 2 page, and the project-scoping<Note>that page carries moved into the template so a run cannot delete it. The cookbook banner matches the Opik 2 optimizer notebook slug again, restoring its Colab button.update_cookbooks.shonly ever generated pages into the v1 tree, so it goes too — the Opik 2 cookbook pages are maintained by hand.Reviewer notes, called out because they are judgement calls rather than mechanical edits:
/docs/opik/tracing/log_traces) are adjacent scope. Those URLs 404 today, before this PR, and are probably the most-linked Opik URLs on the web. The map was already built, so the fix was mechanical. Happy to drop that block if you would rather keep this PR strictly to the/v1/removal.roadmap,testing/pytest_integration,prompt_engineering/improve,evaluation/evaluate_multimodal,evaluation/evaluate_prompt,evaluation/update_existing_experimentand thequickstart_notebookcookbook. If any of that content should exist in Opik 2, it is a follow-up.generate_fern_docs.pybrings it under themypy — optimizerhook for the first time and the commit was rejected. The failure is pre-existing: the unmodified file at HEAD produces the identical two errors, and so does every sibling script insdks/opik_optimizer/scripts/that importsopik_optimizer, because the hook environment does not install that package. Per the repo policy (fix in place, else inline with a reason, never a global config ignore) the two imports carry an inline# type: ignore[import-not-found]with that reason. The root cause — mypy cannot resolveopik_optimizerfor anything underscripts/— deserves its own ticket.Change checklist
Issues
No tracking ticket or GitHub issue — requested directly, hence the
[NA]key.AI-WATERMARK
AI-WATERMARK: yes
canonical-url, generated thedocs.ymlredirect entries, inlined the navigation, deleted the v1 tree, rewrote the stale/v1/links, repointed the generators, and ran the verification below.Testing
Environment: local, docs preview from a git worktree on this branch.
Static checks:
0 errors. The 4 warnings are pre-existing (accent-colour contrast, the
POSTHOG_API_HOSTplaceholder) plus themissing-redirectsrule, which skips without an authorized call to Fern (FDR returns 403) — the sweeps below cover that gap instead.Redirect coverage, offline: modelled Fern's matcher (first match wins,
:slugand:slug*) over 982 URLs — the full published sitemap (714), all 258 v1 URLs, every unversioned Opik 1 path, and/latest/....Redirect coverage, live against
fern docs dev: requested 381 URLs (all 258 v1 URLs, all changed unversioned paths, every bare section root,/latest/..., plus sampled generated REST API and changelog URLs)./agent_optimization/quickstart_notebooklands onoptimizer_introduction_cookbook(a pre-existing redirect, and both slugs render the same MDX file), and/v1/reference/rest-apilands on/reference/rest-api/overviewvia Fern's own section-root resolution.Internal links: checked every root-relative link in
docs-v2. The only two failures are pre-existing/tracing/integrations/langchainlinks inintegrations/langserve.mdx, which resolve through an existing redirect and are untouched here.Hooks:
pre-commitpasses on the changed files, includingmypy — optimizer,ruff,actionlintandzizmor.scripts/precommit-detect-hooks.pyconfirms CI routesgenerate_fern_docs.pyto the mypy leg, which is why that hook had to go green rather than be skipped.Not run: no automated docs test suite exists for this module, and the
missing-redirectsrule cannot run locally without Fern credentials. Worth re-checking that rule on the deploy preview, since it compares against the published site.Documentation
This PR is the documentation change. Alongside the content removal it updates the docs-about-docs so contributors and agents stop being pointed at the deleted tree: the
write-docs,documentationandopik-integrationsskills,CONTRIBUTING.md,apps/opik-documentation/AGENTS.md, the templates README, the Python SDK README, the Sphinx metrics index, and the publishedcontributing/guides/documentation.mdxpage. A repo-wide scan confirms no remaining references tofern/docs/,fern/versions/*.ymlorupdate_cookbooks.sh.🤖 Generated with Claude Code