docs: add documentation versioning support

.github/workflows/manual_release_stable.yaml

@@ -102,15 +102,75 @@ 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'])")"
+          MAJOR_MINOR="$(echo "$VERSION" | cut -d. -f1-2)"
+          export MAJOR_MINOR
+          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

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

@@ -0,0 +1,16 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    # Define the input for the Actor.
+    run_input = {
+        'some': 'input',
+    }
+
+    # Start an Actor and waits for it to finish.
+    call_result = await actor_client.call(run_input=run_input)

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

@@ -0,0 +1,16 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    # Define the input for the Actor.
+    run_input = {
+        'some': 'input',
+    }
+
+    # Start an Actor and waits for it to finish.
+    call_result = actor_client.call(run_input=run_input)

website/versioned_docs/version-2.5/01_introduction/index.mdx

@@ -0,0 +1,58 @@
+---
+id: introduction
+title: Overview
+sidebar_label: Overview
+slug: /
+description: "The official Python library to access the Apify API, with automatic retries, async support, and comprehensive API coverage."
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import UsageAsyncExample from '!!raw-loader!./code/01_usage_async.py';
+import UsageSyncExample from '!!raw-loader!./code/01_usage_sync.py';
+
+The Apify API client for Python is the official library to access the [Apify REST API](/api/v2) from your Python applications. It provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API.
+
+The client simplifies interaction with the Apify platform by providing:
+
+- Intuitive methods for working with [Actors](/platform/actors), [datasets](/platform/storage/dataset), [key-value stores](/platform/storage/key-value-store), and other Apify resources
+- Both synchronous and asynchronous interfaces for flexible integration
+- Built-in [retries with exponential backoff](../02_concepts/05_retries.mdx) for failed requests
+- Comprehensive API coverage with JSON encoding (UTF-8) for all requests and responses
+
+## Prerequisites
+
+`apify-client` requires Python 3.11 or higher. Python is available for download on the [official website](https://www.python.org/downloads/). Check your current Python version by running:
+
+```bash
+python --version
+```
+
+## Installation
+
+The Apify client is available as the [`apify-client`](https://pypi.org/project/apify-client/) package on PyPI.
+
+```bash
+pip install apify-client
+```
+
+## Quick example
+
+Here's an example showing how to run an Actor and retrieve its results:
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {UsageAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {UsageSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+> You can find your API token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console. See the [Quick start guide](./quick-start.mdx) for more details on authentication.