Connecting TABenchmark to Read the Docs (PI-only, one time)

Everything else about the documentation site is automated by .readthedocs.yaml and the docs CI job. This one step needs a person with admin on UMN-Choi-Lab/TABenchmark and is the only manual action to bring the site live.

Merge the config to main first. The importer triggers the first build the moment the project is added, so .readthedocs.yaml (and the docs extra) must already be on main.

  1. Go to https://app.readthedocs.org/ and Log in with GitHub (the account needs admin on the repo).

  2. Dashboard → Add project → type TABenchmark and click the repo in the list.

    • If it does not appear, install the Read the Docs GitHub App when prompted: on GitHub choose the UMN-Choi-Lab org → Only select repositories → TABenchmark → Install (an org owner must approve if you are not one). RTD uses a GitHub App now, so there is no manual webhook to configure.

  3. Click Continue → in the pre-filled fields set Name to tabenchmark (this becomes the slug and URL — https://tabenchmark.readthedocs.io/ — and it was free as of 2026-07-16; confirm it still shows available). Default branch main → Next → at the configuration-file step click This file exists. The first build starts automatically.

  4. Verify pushes build: push any commit to main and watch the build appear under Builds. (No webhook step — the GitHub App handles it.)

  5. Enable PR previews: project Settings → Pull request builds → tick Build pull requests for this project → Update. A docs/readthedocs.org:tabenchmark status then appears on PRs, serving the preview from org.readthedocs.build. Leave it non-required — the docs CI job is the merge gate, so merges never wait on RTD Community’s 2-build concurrency. PRs opened before enabling need one new commit to get a preview.

  6. Versions: Admin → Versions — keep latest (tracks main) as the default. Do not activate stable yet: the repo is 0.x with a weekly-moving roster, so a frozen stable would only make the landing page stale. At the first public release tag (paper / v1.0), push the semver tag, activate the stable version RTD materializes, and set it as the default.

Watch the first build’s wall time. The RTD Community tier caps a build at 15 minutes (7 GB RAM, 2 concurrent builds). The cold build measured ~3.3 min locally (mirror assembly + 47 executed notebooks); on an RTD builder — at the plan’s ~3× slowdown, plus the .[docs,viz] install and the ~131 MB data prefetch — expect roughly ~10 min, i.e. inside the 15-min cap but not by a wide margin. If a future tree pushes past it, the pressure valve is nb_execution_excludepatterns in docs/conf.py: exclude the slowest notebooks from execution (they still render un-executed) rather than dropping them.

Because RTD cannot be built without the PI’s account, this is also where the config’s sphinx:-key requirement (see .readthedocs.yaml) gets its first real end-to-end check: confirm the first build runs the .[docs,viz] install and the two-step build.jobs.build.html — if the install is skipped, the doctype inference regressed.