ADS-110: Introduce versioning for the Ads documentation (freeze v1, restructure as v2)

[MaartenRimaux]

ADS-110 — Introduce versioning for the Ads documentation

Freezes the current Ads docs (legacy Signaling Service product) as v1 and makes the working copy v2, mirroring the THEOlive versioning setup. This is the foundation for the Ads docs restructure (epic ADS-98). Targets the long-lived restructure branch ads-docs-v2.

Changes

Area	Change
ads_versioned_docs/version-v1/	v1 snapshot created with docusaurus docs:version:ads v1 (incl. frozen api/ads-client.swagger.json; generated API .mdx stays gitignored and is rebuilt from the frozen spec)
ads_versioned_sidebars/version-v1-sidebars.json	Frozen sidebar; links pointed at /ads/v1/... (mirrors THEOlive v1 sidebar)
ads_versions.json	Registers v1
docusaurus.config.ts — ads plugin	lastVersion: 'current', versions: { current: { label: 'v2' }, v1: { label: 'v1', banner: 'none' } }
docusaurus.config.ts — ads-api openapi plugin	Current entry labeled v2; new signalingV1 entry generating the legacy Signaling Service reference from the frozen spec into the versioned dir (mirrors theoLiveV1OpenApiOptions)
docusaurus.config.ts — navbar	docsVersionDropdown for the ads plugin (auto-hidden off /ads/ routes by the existing swizzled wrapper)
docusaurus.config.ts — createRedirects	/ads/v1/<page> gains an /ads/<page> origin, so old deep links keep resolving once v2 pages move during the restructure
package.json	gen-api-docs / clean-api-docs use --all-versions for ads-api (mirrors theolive-api)
.prettierignore	Ignore generated ads_versioned_docs/*/api/ output

Decision log

• Long-lived branch named ads-docs-v2 (as suggested in the ticket); this PR targets it, not main. Alternative: ticket-prefixed name — rejected to keep the branch product-scoped for the whole epic.
• createRedirects covers all of /ads/v1/, not just the API subtree (THEOlive only covers /theolive/v1/api/): the whole Ads doc tree will move during the restructure. While v1 ≡ v2, colliding redirect origins are filtered by @docusaurus/plugin-client-redirects with a warning (onDuplicateRoutes: 'warn' default) — verified in the plugin source; they activate automatically as v2 pages move.
• redirectsAds.json unchanged: existing /theoads/... → /ads/... entries chain through the new rule once v2 pages move. Note for later restructure tickets: the plugin validates static to targets, so those entries must be revisited when v2 pages are removed.
• No noIndex on v1: mirrors THEOlive v1 exactly (banner: 'none' only), per ticket.
• v1 snapshot keeps static/ copy: default docs:version behavior; the live ads/static remains the served dir. Restructure tickets must keep referenced files (e.g. GAM template) available.

Validation

• npm run typecheck ✅ (after full gen-api-docs)
• npm run lint ✅
• npm run check-format ✅
• npx docusaurus gen-api-docs all --plugin-id ads-api --all-versions ✅ regenerates the v1 reference from the frozen spec
• Full npm run build not run (skipped by request — heavy submodule init); PR preview CI should confirm both versions render

Before merging

• PR preview: /ads/ renders labeled v2 with version dropdown
• PR preview: /ads/v1/ renders incl. Signaling Service API reference
• Full build passes in CI (onBrokenLinks: 'throw')

Follow-ups

• Restructure v2 content (subsequent ADS tickets in epic ADS-98)
• Revisit redirectsAds.json static targets when v2 pages are removed

Ticket: ADS-110 (parent epic ADS-98)

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://THEOplayer.github.io/documentation/pr-preview/pr-739/
Built to branch gh-pages at 2026-07-15 12:15 UTC. Preview will be ready when the GitHub Pages deployment is complete.