[DOCS] POC multi-version build.

[genedan]

Summary of Changes

Test PR - will not be merged. This is a POC to show what a multi-version docs deployment would look like. Much of the code was written specifically to get the preview up and wouldn't be part of a production deployment. The amount of code change would be minimal with the right choice of theme selection and/or configuring the RTD account settings.

This PR:

• Removes the RTD flyout menu in the lower right hand corner
• Adds a dropdown menu at the top of the navbar showing links to different docs versions. For the POC, this is configured to be a list of deployable minor versions, but any version that can be deployed can be included in the dropdown.

Let me know what you think:

Go = we deploy, I close this PR and open a new one with the real deployment settings (I might need help with RTD access)
No go = close out issue #566 with no changes

Related GitHub Issue(s)

#566

AI/LLM Usage

Claude

Additional Context for Reviewers

Submitter's Checklist

• I have reviewed and am adhering to the standards outlined in the project Governing Doc.
• The PR subject title summarizes the changes, with one proper prefix ([FIX], [FEAT], [DOCS], [TST], [CHORE], or [BRK]).
• I am a human (not a bot), and this PR form is written by a human.

Reviewer's Checklist

• The implementation addresses the associated issue(s).
• The implementation is appropriate, maintainable, and follows ARCHITECTURE.md.
• PR subject title has the proper prefix and the subject is appropriate.
• Relevant issue(s) are linked.
• AI/LLM usage is disclosed and appropriate.
• Documentation and tests are appropriate.
• CI tests passed, or any failures are acceptable.
• Leave a comment with the final recommendation (e.g. approve as is, request a secondary review, or flag an area for more review).

---

Note

Low Risk
Changes are limited to documentation build, theme assets, and CI/RTD hooks; library runtime behavior is unaffected, though RTD pre/post-build steps add build-time complexity.

Overview
This is a proof-of-concept for multi-version documentation: readers get a header dropdown (sphinx-book-theme version switcher) instead of Read the Docs’ corner flyout, which custom CSS hides.

Build pipeline: generate_switcher.py writes docs/_static/switcher.json from the Read the Docs API (with a checked-in fallback). prep_sphinx_conf.py now also patches generated conf.py so each RTD build sets version_match and a per-version json_url to that build’s own menu. Jupyter Book config gains recursive_update, static assets, a version-switcher.html override, and switcher theme options.

POC-only (documented for removal in a real rollout): SWITCHER_DEMO, hardcoded demo releases, build_demo_versions.py (nests prior tag docs under the current build so links work without activating versions on RTD), and extra RTD pre_build/post_build steps. For local/CI review, .github/scripts/build_versioned_docs.py plus docs-preview.yml build many git refs in parallel and upload an artifact.

Not merged as-is per the PR description—the production path would drop demo nesting and rely on RTD version activation plus slimmer config.

^{Reviewed by Cursor Bugbot for commit 63ca199. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 15.2% of exported symbols fully typed (212 / 1399)

	Known	Ambiguous	Unknown	Total
Project (head)	212	111	1076	1399

Other symbols referenced but not exported by chainladder: 13

	Known	Ambiguous	Unknown	Total
Other (head)	3	1	9	13

Symbols without documentation:

• Functions without docstring: 328
• Functions without default param: 0
• Classes without docstring: 10

Patch (exported symbols added or changed by this PR): no exported symbol type-completeness changes detected.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.30%. Comparing base (2f302f9) to head (63ca199).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1407   +/-   ##
=======================================
  Coverage   92.30%   92.30%           
=======================================
  Files         100      100           
  Lines        5797     5797           
  Branches      713      713           
=======================================
  Hits         5351     5351           
  Misses        325      325           
  Partials      121      121           

Flag	Coverage Δ
unittests	92.30% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c2630fc. Configure here.}

[cursor]

Ext-block guard never matches

Low Severity

EXT_MARKER looks for a single-quoted '_ext' path, but EXT_BLOCK writes double quotes. The idempotency check never sees the text it just inserted, so rerunning prep_sphinx_conf.py prepends the sys.path block again.

Additional Locations (1)

• docs/prep_sphinx_conf.py#L66-L68

 

^{Reviewed by Cursor Bugbot for commit c2630fc. Configure here.}