[DISCUSSION] Migrate documentation to Great Docs + GitHub Pages

[EKtheSage]

Opening this as a discussion before any implementation work. Want to gather input from maintainers on whether to migrate the docs site away from the current JupyterBook + ReadTheDocs setup to Great Docs (Posit) hosted on GitHub Pages.

Why migrate

1. Modern, opinionated Python docs framework

Great Docs (https://posit-dev.github.io/great-docs/) is purpose-built for Python packages. It uses Quarto under the hood and provides a single-command setup (great-docs init) plus auto-generated API reference. The look and feel matches what users now expect from libraries like Polars, Ibis, FastAPI: clean, searchable, dark mode, minimal navigation friction.

2. ReadTheDocs ads

ReadTheDocs displays ads on the free tier. For a CAS-affiliated project, ad-free hosting is preferable.

3. GitHub Pages benefits

• No ads, free, deploys directly from a GitHub Action triggered on main.
• Great Docs has a setup-github-pages command that scaffolds the workflow for you.
• Build logs live in GitHub Actions alongside test/CI runs, making it easier to debug failures.
• Simpler infrastructure surface area: one less external service to depend on.

4. AI-friendly outputs

Great Docs auto-generates llms.txt and llms-full.txt for AI assistant indexing, plus an "Agent Skills" output. Given how many users now interact with codebases through AI tools, this is increasingly valuable.

5. Subsumes existing requests

Issue #566 (multi-version documentation) is straightforward in Quarto/Great Docs. The source-link work in #710 (sphinx.ext.linkcode) would need a corresponding mechanism, which Quarto provides natively.

Migration cost is lower than it looks

A natural concern is that all the existing notebook content under docs/gallery/ and docs/getting_started/tutorials/ would need to be converted to Quarto's .qmd format. That isn't actually required: Quarto natively supports .ipynb files (see https://quarto.org/docs/tools/jupyter-lab.html). Existing notebooks can keep their .ipynb extension and be rendered directly by Quarto. New content can be authored in either format depending on author preference.

Open questions

• Custom Sphinx extension: the ext_linkcode extension added in Add links to object source code in API Reference section #710 is Sphinx-specific. We would need a Quarto equivalent or accept losing the linkcode_resolve customization.
• URL stability: ReadTheDocs URLs are deeply linked across the actuarial community. We should plan redirects.

Proposed next step

Maintainer feedback on whether this direction is acceptable in principle. If so, I can scope a multi-phase migration plan (small content port first to validate, then bulk migration, then DNS/redirect work).

[genedan]

Build logs live in GitHub Actions alongside test/CI runs, making it easier to debug failures.

This feature sticks out to me as being the most useful, and no ads would be super nice. I don't know much about using RTD so John and Kenneth can opine on whether there are features there that are essential. Otherwise, I can adapt to whatever the group decides.

Just throwing this out there as another idea, but I actually pay for a VPS for my own projects. The main pro is that it's just a blank OS so you can do whatever you want with it, and moving is as easy as just changing hosting providers. It also integrates with GitHub actions. Cons are things like domain registration, and personal expenses. There's also no web interface, all the debugging is via the terminal unless you want to install more software. However, nobody would ever want to register a name like faslr, so for me the cost is low.

chainladder.com is expensive! That's no surprise, you picked the best name possible for the package.

[jbogaardt]

Im not wed to readthedocs. It was the defacto standard 8 years ago when we set up. That said, it has served us well and we have enough history there that the search rankings are solid. Let me know if adding you as admin to readthedocs alleviates some of the painpoints on not seeing the builds.

[EKtheSage]

chainladder.ai is cheap, comparably speaking.