diff --git a/docs/01_overview/code/01_usage_async.py b/docs/01_introduction/code/01_usage_async.py
similarity index 100%
rename from docs/01_overview/code/01_usage_async.py
rename to docs/01_introduction/code/01_usage_async.py
diff --git a/docs/01_overview/code/01_usage_sync.py b/docs/01_introduction/code/01_usage_sync.py
similarity index 100%
rename from docs/01_overview/code/01_usage_sync.py
rename to docs/01_introduction/code/01_usage_sync.py
diff --git a/docs/01_overview/code/02_auth_async.py b/docs/01_introduction/code/02_auth_async.py
similarity index 100%
rename from docs/01_overview/code/02_auth_async.py
rename to docs/01_introduction/code/02_auth_async.py
diff --git a/docs/01_overview/code/02_auth_sync.py b/docs/01_introduction/code/02_auth_sync.py
similarity index 100%
rename from docs/01_overview/code/02_auth_sync.py
rename to docs/01_introduction/code/02_auth_sync.py
diff --git a/docs/01_overview/code/03_dataset_async.py b/docs/01_introduction/code/03_dataset_async.py
similarity index 100%
rename from docs/01_overview/code/03_dataset_async.py
rename to docs/01_introduction/code/03_dataset_async.py
diff --git a/docs/01_overview/code/03_dataset_sync.py b/docs/01_introduction/code/03_dataset_sync.py
similarity index 100%
rename from docs/01_overview/code/03_dataset_sync.py
rename to docs/01_introduction/code/03_dataset_sync.py
diff --git a/docs/01_overview/code/03_input_async.py b/docs/01_introduction/code/03_input_async.py
similarity index 100%
rename from docs/01_overview/code/03_input_async.py
rename to docs/01_introduction/code/03_input_async.py
diff --git a/docs/01_overview/code/03_input_sync.py b/docs/01_introduction/code/03_input_sync.py
similarity index 100%
rename from docs/01_overview/code/03_input_sync.py
rename to docs/01_introduction/code/03_input_sync.py
diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx
new file mode 100644
index 00000000..d0076ee2
--- /dev/null
+++ b/docs/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:
+
+
+
+
+ {UsageAsyncExample}
+
+
+
+
+ {UsageSyncExample}
+
+
+
+
+> 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.
diff --git a/docs/01_introduction/quick-start.mdx b/docs/01_introduction/quick-start.mdx
new file mode 100644
index 00000000..5832c2a7
--- /dev/null
+++ b/docs/01_introduction/quick-start.mdx
@@ -0,0 +1,106 @@
+---
+id: quick-start
+title: Quick start
+sidebar_label: Quick start
+description: "Get started with the Apify API client for Python by running an Actor and retrieving results from its dataset."
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import AuthAsyncExample from '!!raw-loader!./code/02_auth_async.py';
+import AuthSyncExample from '!!raw-loader!./code/02_auth_sync.py';
+import InputAsyncExample from '!!raw-loader!./code/03_input_async.py';
+import InputSyncExample from '!!raw-loader!./code/03_input_sync.py';
+import DatasetAsyncExample from '!!raw-loader!./code/03_dataset_async.py';
+import DatasetSyncExample from '!!raw-loader!./code/03_dataset_sync.py';
+
+Learn how to authenticate, run Actors, and retrieve results using the Apify API client for Python.
+
+---
+
+## Step 1: Authenticate the client
+
+To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). You can find your token under the [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing it (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor.
+
+
+
+
+ {AuthAsyncExample}
+
+
+
+
+ {AuthSyncExample}
+
+
+
+
+:::warning Secure access
+
+The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications.
+
+:::
+
+## Step 2: Run an Actor
+
+To start an Actor, call the [`apify_client.actor()`](/reference/class/ActorClient) method with the Actor's ID (e.g., `john-doe/my-cool-actor`). The Actor's ID is a combination of the Actor owner's username and the Actor name. You can run both your own Actors and Actors from [Apify Store](https://apify.com/store).
+
+To define the Actor's input, pass a dictionary to the [`call()`](/reference/class/ActorClient#call) method that matches the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema). The input can include URLs to scrape, search terms, or other configuration data.
+
+
+
+
+ {InputAsyncExample}
+
+
+
+
+ {InputSyncExample}
+
+
+
+
+## Step 3: Get results from the dataset
+
+To get the results from the dataset, call the [`apify_client.dataset()`](/reference/class/DatasetClient) method with the dataset ID, then call [`list_items()`](/reference/class/DatasetClient#list_items) to retrieve the data. You can get the dataset ID from the Actor's run dictionary (represented by `defaultDatasetId`).
+
+
+
+
+ {DatasetAsyncExample}
+
+
+
+
+ {DatasetSyncExample}
+
+
+
+
+:::note Dataset access
+
+Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response, you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs).
+
+:::
+
+## Next steps
+
+### Concepts
+
+To learn more about how the client works, check out the Concepts section in the sidebar:
+
+- [Asyncio support](../02_concepts/01_async_support.mdx) - asynchronous programming with the client
+- [Single and collection clients](../02_concepts/02_single_collection_clients.mdx) - resource clients and collection clients
+- [Error handling](../02_concepts/04_error_handling.mdx) - automatic data extraction and error debugging
+- [Retries](../02_concepts/05_retries.mdx) - automatic retries with exponential backoff
+- [Pagination](../02_concepts/08_pagination.mdx) - iterating through large result sets
+
+### Guides
+
+For practical examples of common tasks, see the Guides section:
+
+- [Pass input to an Actor](../03_guides/01_passing_input_to_actor.mdx)
+- [Retrieve Actor data](../03_guides/03_retrieve_actor_data.mdx)
+- [Integrate with data libraries](../03_guides/04_integration_with_data_libraries.mdx)
diff --git a/docs/01_overview/index.mdx b/docs/01_overview/index.mdx
deleted file mode 100644
index f861f3d1..00000000
--- a/docs/01_overview/index.mdx
+++ /dev/null
@@ -1,156 +0,0 @@
----
-id: overview
-title: Overview
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import CodeBlock from '@theme/CodeBlock';
-
-import AuthAsyncExample from '!!raw-loader!./code/02_auth_async.py';
-import AuthSyncExample from '!!raw-loader!./code/02_auth_sync.py';
-import UsageAsyncExample from '!!raw-loader!./code/01_usage_async.py';
-import UsageSyncExample from '!!raw-loader!./code/01_usage_sync.py';
-import InputAsyncExample from '!!raw-loader!./code/03_input_async.py';
-import InputSyncExample from '!!raw-loader!./code/03_input_sync.py';
-import DatasetAsyncExample from '!!raw-loader!./code/03_dataset_async.py';
-import DatasetSyncExample from '!!raw-loader!./code/03_dataset_sync.py';
-
-## Introduction
-
-The [Apify client for Python](https://github.com/apify/apify-client-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.
-
-Key features:
-
-- Synchronous and asynchronous interfaces for flexible integration
-- Automatic retries for improved reliability
-- JSON encoding with UTF-8 for all requests and responses
-- Comprehensive API coverage for [Actors](/platform/actors), [datasets](/platform/storage/dataset), [key-value stores](/platform/storage/key-value-store), and more
-
-## Prerequisites
-
-Before installing the Apify client, ensure your system meets the following requirements:
-
-- _An Apify account_
-- _Python 3.11 or higher_: You can download Python from the [official website](https://www.python.org/downloads/).
-- _Python package manager_: While this guide uses [pip](https://pip.pypa.io/en/stable/), you can also use any package manager you want.
-
-To verify that Python and pip are installed, run the following commands:
-
-```sh
-python --version
-```
-
-```sh
-pip --version
-```
-
-If these commands return the respective versions, you're ready to continue.
-
-## Installation
-
-The Apify client is available as the [`apify-client`](https://pypi.org/project/apify-client/) package on PyPI. To install it, run:
-
-```sh
-pip install apify-client
-```
-
-After installation, verify that the client is installed correctly by checking its version:
-
-```sh
-python -c 'import apify_client; print(apify_client.__version__)'
-```
-
-## Authentication and initialization
-
-To use the client, you need an [API token](/platform/integrations/api#api-token). You can find your token under the [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing it as a parameter to the `ApifyClient` constructor.
-
-
-
-
- {AuthAsyncExample}
-
-
-
-
- {AuthSyncExample}
-
-
-
-
-:::warning Secure access
-
-The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications.
-
-:::
-
-## Quick start
-
-Now that you have the client set up, let's explore how to run Actors on the Apify platform, provide input to them, and retrieve their results.
-
-### Running your first Actor
-
-To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API token. The Actor's ID is a combination of the Actor name and the Actor owner's username. Use the [`ActorClient`](/reference/class/ActorClient) to run the Actor and wait for it to complete. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store).
-
-
-
-
- {UsageAsyncExample}
-
-
-
-
- {UsageSyncExample}
-
-
-
-
-### Providing input to Actor
-
-Actors often require input, such as URLs to scrape, search terms, or other configuration data. You can pass input as a JSON object when starting the Actor using the [`ActorClient.call`](/reference/class/ActorClient#call) method. Actors respect the input schema defined in the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema).
-
-
-
-
- {InputAsyncExample}
-
-
-
-
- {InputSyncExample}
-
-
-
-
-### Getting results from the dataset
-
-To get the results from the dataset, you can use the [`DatasetClient`](/reference/class/DatasetClient) ([`ApifyClient.dataset`](/reference/class/ApifyClient#dataset)) and [`DatasetClient.list_items`](/reference/class/DatasetClient#list_items) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run dictionary (represented by `defaultDatasetId`).
-
-
-
-
- {DatasetAsyncExample}
-
-
-
-
- {DatasetSyncExample}
-
-
-
-
-:::note Dataset access
-
-Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response, you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs).
-
-:::
-
-## Next steps
-
-Now that you're familiar with the basics, explore more advanced features:
-
-- [Asyncio support](/concepts/asyncio-support) - Learn about asynchronous programming with the client
-- Common use-case examples like:
- - [Passing an input to Actor](/api/client/python/docs/examples/passing-input-to-actor)
- - [Retrieve Actor data](/api/client/python/docs/examples/retrieve-actor-data)
-- [API Reference](/api/client/python/reference) - Browse the complete API documentation
diff --git a/docs/03_examples/01_passing_input_to_actor.mdx b/docs/03_guides/01_passing_input_to_actor.mdx
similarity index 100%
rename from docs/03_examples/01_passing_input_to_actor.mdx
rename to docs/03_guides/01_passing_input_to_actor.mdx
diff --git a/docs/03_examples/02_manage_tasks_for_reusable_input.mdx b/docs/03_guides/02_manage_tasks_for_reusable_input.mdx
similarity index 100%
rename from docs/03_examples/02_manage_tasks_for_reusable_input.mdx
rename to docs/03_guides/02_manage_tasks_for_reusable_input.mdx
diff --git a/docs/03_examples/03_retrieve_actor_data.mdx b/docs/03_guides/03_retrieve_actor_data.mdx
similarity index 100%
rename from docs/03_examples/03_retrieve_actor_data.mdx
rename to docs/03_guides/03_retrieve_actor_data.mdx
diff --git a/docs/03_examples/04_integration_with_data_libraries.mdx b/docs/03_guides/04_integration_with_data_libraries.mdx
similarity index 100%
rename from docs/03_examples/04_integration_with_data_libraries.mdx
rename to docs/03_guides/04_integration_with_data_libraries.mdx
diff --git a/docs/03_examples/code/01_input_async.py b/docs/03_guides/code/01_input_async.py
similarity index 100%
rename from docs/03_examples/code/01_input_async.py
rename to docs/03_guides/code/01_input_async.py
diff --git a/docs/03_examples/code/01_input_sync.py b/docs/03_guides/code/01_input_sync.py
similarity index 100%
rename from docs/03_examples/code/01_input_sync.py
rename to docs/03_guides/code/01_input_sync.py
diff --git a/docs/03_examples/code/02_tasks_async.py b/docs/03_guides/code/02_tasks_async.py
similarity index 100%
rename from docs/03_examples/code/02_tasks_async.py
rename to docs/03_guides/code/02_tasks_async.py
diff --git a/docs/03_examples/code/02_tasks_sync.py b/docs/03_guides/code/02_tasks_sync.py
similarity index 100%
rename from docs/03_examples/code/02_tasks_sync.py
rename to docs/03_guides/code/02_tasks_sync.py
diff --git a/docs/03_examples/code/03_retrieve_async.py b/docs/03_guides/code/03_retrieve_async.py
similarity index 100%
rename from docs/03_examples/code/03_retrieve_async.py
rename to docs/03_guides/code/03_retrieve_async.py
diff --git a/docs/03_examples/code/03_retrieve_sync.py b/docs/03_guides/code/03_retrieve_sync.py
similarity index 100%
rename from docs/03_examples/code/03_retrieve_sync.py
rename to docs/03_guides/code/03_retrieve_sync.py
diff --git a/docs/03_examples/code/04_pandas_async.py b/docs/03_guides/code/04_pandas_async.py
similarity index 100%
rename from docs/03_examples/code/04_pandas_async.py
rename to docs/03_guides/code/04_pandas_async.py
diff --git a/docs/03_examples/code/04_pandas_sync.py b/docs/03_guides/code/04_pandas_sync.py
similarity index 100%
rename from docs/03_examples/code/04_pandas_sync.py
rename to docs/03_guides/code/04_pandas_sync.py
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index cc0cb71a..fb7766aa 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -45,7 +45,7 @@ module.exports = {
title: 'API Client for Python',
items: [
{
- to: 'docs/overview',
+ to: 'docs',
label: 'Docs',
position: 'left',
activeBaseRegex: '/docs(?!/changelog)',
@@ -139,7 +139,7 @@ module.exports = {
...config.themeConfig.footer,
logo: {
...config.themeConfig.footer.logo,
- href: 'docs/introduction/overview',
+ href: 'docs',
},
},
},
diff --git a/website/sidebars.js b/website/sidebars.js
index 5e053e71..23ac8cf3 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -2,7 +2,11 @@ module.exports = {
sidebar: [
{
type: 'doc',
- id: 'overview/overview',
+ id: 'introduction/introduction',
+ },
+ {
+ type: 'doc',
+ id: 'introduction/quick-start',
},
{
type: 'category',
@@ -17,12 +21,12 @@ module.exports = {
},
{
type: 'category',
- label: 'Examples',
+ label: 'Guides',
collapsed: true,
items: [
{
type: 'autogenerated',
- dirName: '03_examples',
+ dirName: '03_guides',
},
],
},
diff --git a/website/src/pages/index.js b/website/src/pages/index.js
index 9290ba17..232142c7 100644
--- a/website/src/pages/index.js
+++ b/website/src/pages/index.js
@@ -5,7 +5,7 @@ export default function Home() {
const history = useHistory();
useEffect(() => {
- history.replace('/api/client/python/docs/introduction/overview');
+ history.replace('/api/client/python/docs');
}, [history]);
return null;