docs: add documentation versioning support

Add Docusaurus documentation versioning to store the last stable version
docs (v2.5) alongside "next" for unreleased features. This includes the
version dropdown in the navbar, versioned docs/sidebars/API reference
snapshots, a CI workflow step to automatically version docs on release,
and extended ty/ruff overrides for versioned doc code samples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vdusek

.github/workflows/manual_release_stable.yaml

@@ -102,15 +102,74 @@ jobs:
       - name: Publish package to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
+  version_docs:
+    name: Version docs
+    needs: [release_prepare, changelog_update, pypi_publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      NODE_VERSION: 22
+      PYTHON_VERSION: 3.14
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Set up uv package manager
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install Python dependencies
+        run: uv run poe install-dev
+
+      - name: Install website dependencies
+        run: |
+          cd website
+          yarn install
+
+      - name: Snapshot the current version
+        run: |
+          cd website
+          VERSION=$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('../pyproject.toml').read_text())['project']['version'])")
+          export MAJOR_MINOR=$(echo $VERSION | cut -d. -f1-2)
+          rm -rf versioned_docs/version-$MAJOR_MINOR
+          rm -rf versioned_sidebars/version-$MAJOR_MINOR-sidebars.json
+          jq 'map(select(. != env.MAJOR_MINOR))' versions.json > tmp.json && mv tmp.json versions.json
+          bash build_api_reference.sh
+          npx docusaurus docs:version $MAJOR_MINOR
+          npx docusaurus api:version $MAJOR_MINOR
+
+      - name: Commit and push the version snapshot
+        uses: EndBug/add-and-commit@v9
+        with:
+          author_name: Apify Release Bot
+          author_email: noreply@apify.com
+          message: "docs: update versioned docs for ${{ needs.release_prepare.outputs.version_number }}"
+
   doc_release:
     name: Doc release
-    needs: [changelog_update, pypi_publish]
+    needs: [changelog_update, pypi_publish, version_docs]
     permissions:
       contents: write
       pages: write
       id-token: write
     uses: ./.github/workflows/_release_docs.yaml
     with:
-      # Use the ref from the changelog update to include the updated changelog.
-      ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
+      # Use the default branch to include both the changelog update and the versioned docs snapshot.
+      ref: ${{ github.event.repository.default_branch }}
     secrets: inherit

pyproject.toml

@@ -78,6 +78,9 @@ include = [
     "docs/**/*.py",
     "website/**/*.py",
 ]
+exclude = [
+    "website/versioned_docs/**",
+]
 
 [tool.ruff.lint]
 select = ["ALL"]
@@ -181,6 +184,7 @@ python-version = "3.11"
 
 [tool.ty.src]
 include = ["src", "tests", "scripts", "docs", "website"]
+exclude = ["website/versioned_docs"]
 
 [[tool.ty.overrides]]
 include = ["docs/**/*.py", "website/**/*.py"]

website/docusaurus.config.js

@@ -4,6 +4,7 @@ const { config } = require('@apify/docs-theme');
 
 const { externalLinkProcessor } = require('./tools/utils/externalLink');
 const { groupSort } = require('./transformDocs.js');
+const versions = require('./versions.json');
 
 const { absoluteUrl } = config;
 
@@ -67,6 +68,17 @@ module.exports = {
                             label: 'GitHub',
                             position: 'left',
                         },
+                        {
+                            type: 'docsVersionDropdown',
+                            position: 'left',
+                            className: 'navbar__item',
+                            'data-api-links': JSON.stringify([
+                                'reference/next',
+                                ...versions.map((version, i) => (i === 0 ? 'reference' : `reference/${version}`)),
+                            ]),
+                            dropdownItemsBefore: [],
+                            dropdownItemsAfter: [],
+                        },
                     ],
                 },
             },
@@ -124,13 +136,20 @@ module.exports = {
                     includeGeneratedIndex: false,
                     includePages: true,
                     relativePaths: false,
+                    excludeRoutes: [
+                        '/api/client/python/reference/[0-9]*/**',
+                        '/api/client/python/reference/[0-9]*',
+                        '/api/client/python/reference/next/**',
+                        '/api/client/python/reference/next',
+                    ],
                 },
             },
         ],
         ...config.plugins,
     ],
     themeConfig: {
         ...config.themeConfig,
+        versions,
         tableOfContents: {
             ...config.themeConfig.tableOfContents,
             maxHeadingLevel: 5,

website/versioned_docs/version-2.5/.gitignore

@@ -0,0 +1 @@
+changelog.md

website/versioned_docs/version-2.5/01_introduction/code/01_usage_async.py

@@ -0,0 +1,21 @@
+from apify_client import ApifyClientAsync
+
+# You can find your API token at https://console.apify.com/settings/integrations.
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+
+    # Start an Actor and wait for it to finish.
+    actor_client = apify_client.actor('john-doe/my-cool-actor')
+    call_result = await actor_client.call()
+
+    if call_result is None:
+        print('Actor run failed.')
+        return
+
+    # Fetch results from the Actor run's default dataset.
+    dataset_client = apify_client.dataset(call_result.default_dataset_id)
+    list_items_result = await dataset_client.list_items()
+    print(f'Dataset: {list_items_result}')

website/versioned_docs/version-2.5/01_introduction/code/01_usage_sync.py

@@ -0,0 +1,21 @@
+from apify_client import ApifyClient
+
+# You can find your API token at https://console.apify.com/settings/integrations.
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+
+    # Start an Actor and wait for it to finish.
+    actor_client = apify_client.actor('john-doe/my-cool-actor')
+    call_result = actor_client.call()
+
+    if call_result is None:
+        print('Actor run failed.')
+        return
+
+    # Fetch results from the Actor run's default dataset.
+    dataset_client = apify_client.dataset(call_result.default_dataset_id)
+    list_items_result = dataset_client.list_items()
+    print(f'Dataset: {list_items_result}')

website/versioned_docs/version-2.5/01_introduction/code/02_auth_async.py

@@ -0,0 +1,8 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    # Client initialization with the API token.
+    apify_client = ApifyClientAsync(TOKEN)

website/versioned_docs/version-2.5/01_introduction/code/02_auth_sync.py

@@ -0,0 +1,8 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    # Client initialization with the API token.
+    apify_client = ApifyClient(TOKEN)

website/versioned_docs/version-2.5/01_introduction/code/03_dataset_async.py

@@ -0,0 +1,11 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+    dataset_client = apify_client.dataset('dataset-id')
+
+    # Lists items from the Actor's dataset.
+    dataset_items = (await dataset_client.list_items()).items

website/versioned_docs/version-2.5/01_introduction/code/03_dataset_sync.py

@@ -0,0 +1,11 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+    dataset_client = apify_client.dataset('dataset-id')
+
+    # Lists items from the Actor's dataset.
+    dataset_items = dataset_client.list_items().items