docs: restore version-2.5 and add version-3.0 (botched v3.0.0 release versioning)

[vdusek]

The v3.0.0 release on 2026-05-20 ran the Version docs job with the pre-bump version 2.5.1 instead of 3.0.0. As a result:

• website/versioned_docs/version-2.5/ was wiped and re-created from the current docs/ directory (which contained v3 content) — so 2.5 now hosts v3 docs.
• website/versioned_docs/version-3.0/ was never created.
• website/versions.json is still ["2.5", "1.12", "0.6"].
• The published docs site at https://docs.apify.com/api/client/python therefore serves v3 content under the 2.5 dropdown entry and has no 3.0 entry at all.

The bad commit is e0a0bc8 (docs: Version docs for v2.5.1 [skip ci]). The workflow log shows: Version: 2.5.1, Major.Minor: 2.5, Major: 2.

The pipeline fix that prevents this from recurring is tracked separately in #806. This issue covers the data restore only — do not touch any workflows.

Expected end state

• website/versions.json equals ["3.0", "2.5", "1.12", "0.6"] (in that order).
• website/versioned_docs/version-2.5/ matches the directory tree at commit 5f7f7b1 — the genuine v2.5 docs:
  • no 04_upgrading/upgrading_to_v3.mdx
  • no 02_concepts/10_custom_http_clients.mdx, 11_timeouts.mdx, 12_typed_models.mdx
  • smaller api-typedoc.json (1820266 bytes)
• website/versioned_sidebars/version-2.5-sidebars.json matches the file at commit 5f7f7b1.
• website/versioned_docs/version-3.0/ exists and is a fresh Docusaurus snapshot of the current docs/ directory — v3 content: upgrading_to_v3.mdx, 10_custom_http_clients.mdx, 11_timeouts.mdx, 12_typed_models.mdx, the v3 api-typedoc.json (~7.5 MB).
• website/versioned_sidebars/version-3.0-sidebars.json exists. Indent with 4 spaces to match the other version-*-sidebars.json files.
• No changelog.md, pyproject.toml, or .ruff_cache/ paths under website/versioned_docs/version-3.0/ — they are gitignored at the repo root (see .gitignore) but easy to accidentally rm from disk and forget.

Suggested approach

Docusaurus' built-in versioning does almost all of this. Recipe verified locally on master:

git checkout -b fix/docs-versioning-v3-restore

# 1. Restore version-2.5 to its pre-bug state.
#    `rm -rf` first — `git checkout <sha> -- <dir>` does NOT delete files that
#    exist in the working tree but not in <sha>.
rm -rf website/versioned_docs/version-2.5
git checkout 5f7f7b1 -- \
  website/versioned_docs/version-2.5 \
  website/versioned_sidebars/version-2.5-sidebars.json \
  website/versions.json

# 2. Generate version-3.0 from current docs/.
cd website
uv run python generate_module_shortcuts.py     # populates module_shortcuts.json (gitignored)
pnpm install
pnpm exec docusaurus docs:version 3.0
pnpm exec docusaurus api:version 3.0
cd ..

# 3. Reformat the new sidebar to 4-space indent (docusaurus writes 2-space).
python3 -c "
import json
p = 'website/versioned_sidebars/version-3.0-sidebars.json'
data = json.load(open(p))
with open(p, 'w') as f:
    json.dump(data, f, indent=4)
    f.write('\n')
"

# 4. Tidy up files docusaurus copied that are gitignored at repo root.
rm -rf website/versioned_docs/version-3.0/.ruff_cache
rm -f \
  website/versioned_docs/version-3.0/changelog.md \
  website/versioned_docs/version-3.0/pyproject.toml

# 5. Commit (use `docs:` prefix so post-merge `Doc release` triggers on master).
git add -A website/versioned_docs/ website/versioned_sidebars/ website/versions.json
git commit -m "docs: restore version-2.5 and add version-3.0"
git push -u origin fix/docs-versioning-v3-restore

Acceptance criteria

• cat website/versions.json outputs ["3.0", "2.5", "1.12", "0.6"] (in that order).
• find website/versioned_docs/version-2.5 -type f | wc -l returns 53.
• ls website/versioned_docs/version-2.5/04_upgrading/ lists only upgrading_to_v2.mdx.
• ls website/versioned_docs/version-3.0/04_upgrading/ lists both upgrading_to_v2.mdx and upgrading_to_v3.mdx.
• wc -c website/versioned_docs/version-2.5/api-typedoc.json returns 1820266.
• git status --short shows no untracked files inside website/versioned_docs/version-3.0/ after the commit.
• The PR uses the docs: conventional commit prefix in its title.
• The PR diff touches only website/versioned_docs/, website/versioned_sidebars/, and website/versions.json. No workflow changes.

References

• Bad commit: e0a0bc8
• Last good state for version-2.5: 5f7f7b1
• Successful release run with the bug visible in logs: https://github.com/apify/apify-client-python/actions/runs/26156928273
• Pipeline fix (separate PR): ci: pass bumped version and post-bump ref to docs jobs in release flow #806
• Existing working draft of this fix: docs: restore version-2.5 and add version-3.0 #805 — will be closed once the agent's PR lands.