From 82c7f74acbe497452adbd5461cb2a8e2aa00d18c Mon Sep 17 00:00:00 2001 From: patrikbraborec Date: Fri, 16 Jan 2026 16:17:09 +0100 Subject: [PATCH 1/3] docs: restructure documentation with separate introduction section Reorganize documentation structure by splitting the overview into three distinct pages: - Introduction: SDK overview and features - Installation: Setup and dependency management - Quick start: Creating and running Actors Also reorganize sections by renaming and moving files: - Move webserver guide from concepts to guides section - Renumber concept pages to maintain proper ordering - Update sidebar configuration to reflect new structure Co-Authored-By: Claude Sonnet 4.5 --- .../code/01_introduction.py | 0 .../code/actor_structure/__init__.py | 0 .../code/actor_structure/__main__.py | 0 .../code/actor_structure/main.py | 0 .../code/actor_structure/py.typed | 0 .../images/apify-create.gif | Bin docs/01_introduction/index.mdx | 45 +++++++++++ docs/01_introduction/installation.mdx | 51 ++++++++++++ .../quick-start.mdx} | 76 +++--------------- .../{10_logging.mdx => 09_logging.mdx} | 8 +- ...configuration.mdx => 10_configuration.mdx} | 2 +- ...pay_per_event.mdx => 11_pay_per_event.mdx} | 4 +- .../{10_log_config.py => 09_log_config.py} | 0 ...{10_logger_usage.py => 09_logger_usage.py} | 0 ...{10_redirect_log.py => 09_redirect_log.py} | 0 ...run.py => 09_redirect_log_existing_run.py} | 0 .../code/{11_config.py => 10_config.py} | 0 ...{12_actor_charge.py => 11_actor_charge.py} | 0 ...arge.py => 11_conditional_actor_charge.py} | 0 .../07_running_webserver.mdx} | 2 +- .../code/07_webserver.py} | 0 website/sidebars.js | 11 ++- 22 files changed, 124 insertions(+), 75 deletions(-) rename docs/{01_overview => 01_introduction}/code/01_introduction.py (100%) rename docs/{01_overview => 01_introduction}/code/actor_structure/__init__.py (100%) rename docs/{01_overview => 01_introduction}/code/actor_structure/__main__.py (100%) rename docs/{01_overview => 01_introduction}/code/actor_structure/main.py (100%) rename docs/{01_overview => 01_introduction}/code/actor_structure/py.typed (100%) rename docs/{01_overview => 01_introduction}/images/apify-create.gif (100%) create mode 100644 docs/01_introduction/index.mdx create mode 100644 docs/01_introduction/installation.mdx rename docs/{01_overview/index.mdx => 01_introduction/quick-start.mdx} (68%) rename docs/02_concepts/{10_logging.mdx => 09_logging.mdx} (96%) rename docs/02_concepts/{11_configuration.mdx => 10_configuration.mdx} (96%) rename docs/02_concepts/{12_pay_per_event.mdx => 11_pay_per_event.mdx} (97%) rename docs/02_concepts/code/{10_log_config.py => 09_log_config.py} (100%) rename docs/02_concepts/code/{10_logger_usage.py => 09_logger_usage.py} (100%) rename docs/02_concepts/code/{10_redirect_log.py => 09_redirect_log.py} (100%) rename docs/02_concepts/code/{10_redirect_log_existing_run.py => 09_redirect_log_existing_run.py} (100%) rename docs/02_concepts/code/{11_config.py => 10_config.py} (100%) rename docs/02_concepts/code/{12_actor_charge.py => 11_actor_charge.py} (100%) rename docs/02_concepts/code/{12_conditional_actor_charge.py => 11_conditional_actor_charge.py} (100%) rename docs/{02_concepts/09_running_webserver.mdx => 03_guides/07_running_webserver.mdx} (95%) rename docs/{02_concepts/code/09_webserver.py => 03_guides/code/07_webserver.py} (100%) diff --git a/docs/01_overview/code/01_introduction.py b/docs/01_introduction/code/01_introduction.py similarity index 100% rename from docs/01_overview/code/01_introduction.py rename to docs/01_introduction/code/01_introduction.py diff --git a/docs/01_overview/code/actor_structure/__init__.py b/docs/01_introduction/code/actor_structure/__init__.py similarity index 100% rename from docs/01_overview/code/actor_structure/__init__.py rename to docs/01_introduction/code/actor_structure/__init__.py diff --git a/docs/01_overview/code/actor_structure/__main__.py b/docs/01_introduction/code/actor_structure/__main__.py similarity index 100% rename from docs/01_overview/code/actor_structure/__main__.py rename to docs/01_introduction/code/actor_structure/__main__.py diff --git a/docs/01_overview/code/actor_structure/main.py b/docs/01_introduction/code/actor_structure/main.py similarity index 100% rename from docs/01_overview/code/actor_structure/main.py rename to docs/01_introduction/code/actor_structure/main.py diff --git a/docs/01_overview/code/actor_structure/py.typed b/docs/01_introduction/code/actor_structure/py.typed similarity index 100% rename from docs/01_overview/code/actor_structure/py.typed rename to docs/01_introduction/code/actor_structure/py.typed diff --git a/docs/01_overview/images/apify-create.gif b/docs/01_introduction/images/apify-create.gif similarity index 100% rename from docs/01_overview/images/apify-create.gif rename to docs/01_introduction/images/apify-create.gif diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx new file mode 100644 index 00000000..2ed6344b --- /dev/null +++ b/docs/01_introduction/index.mdx @@ -0,0 +1,45 @@ +--- +id: overview +title: Introduction +sidebar_label: Introduction +description: 'The official library for creating Apify Actors in Python, providing tools for web scraping, automation, and data storage integration.' +--- + +The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. + +It provides tools and classes for web scraping and automation, allowing you to manage Actor lifecycles, handle data storage, work with proxies, and integrate with popular Python libraries. + +## Example + +Here's a simple example of an Actor that scrapes a web page and stores the result: + +```py +from apify import Actor +from bs4 import BeautifulSoup +import requests + +async def main(): + async with Actor: + input = await Actor.get_input() + response = requests.get(input['url']) + soup = BeautifulSoup(response.content, 'html.parser') + await Actor.push_data({ 'url': input['url'], 'title': soup.title.string }) +``` + +## Features + +The Apify SDK for Python provides: + +- **Actor lifecycle management** - Handle initialization, teardown, and graceful shutdowns +- **Storage management** - Work with Datasets, Key-Value Stores, and Request Queues +- **Event handling** - Respond to Actor events like migration, abort, and system info +- **Proxy management** - Rotate and manage proxies for web scraping +- **Platform integration** - Interact with other Actors, webhooks, and the Apify API +- **Framework compatibility** - Integrate with BeautifulSoup, Playwright, Selenium, Scrapy, and Crawlee + +## Next steps + +- **[Installation](./installation)** - Install the SDK and set up your development environment +- **[Quick start](./quick-start)** - Create and run your first Actor +- **[Concepts](../concepts/actor-lifecycle)** - Learn about core SDK concepts +- **[Guides](../guides/beautiful-soup)** - See how to integrate with popular libraries diff --git a/docs/01_introduction/installation.mdx b/docs/01_introduction/installation.mdx new file mode 100644 index 00000000..e8d6c765 --- /dev/null +++ b/docs/01_introduction/installation.mdx @@ -0,0 +1,51 @@ +--- +title: Installation +sidebar_label: Installation +description: 'Learn how to install the Apify SDK for Python using pip and manage dependencies for your Actor projects.' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +## Requirements + +The Apify SDK requires Python version 3.10 or above to run Python Actors locally. + +## Installation + +The Apify Python SDK is available as [`apify`](https://pypi.org/project/apify/) package on PyPi. To install it, run: + +```bash +pip install apify +``` + +When you create an Actor using the Apify CLI, the Apify SDK for Python is installed for you automatically. + +If you are not developing Apify Actors and you just need to access the Apify API from Python, +consider using the [Apify API client for Python](/api/client/python) directly. + +## Adding dependencies + +First, add the dependencies in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder. + +Then activate the virtual environment in `.venv`: + + + + { +`source .venv/bin/activate` + } + + + { +`.venv\\Scripts\\activate` + } + + + +Finally, install the dependencies: + +```bash +python -m pip install -r requirements.txt +``` diff --git a/docs/01_overview/index.mdx b/docs/01_introduction/quick-start.mdx similarity index 68% rename from docs/01_overview/index.mdx rename to docs/01_introduction/quick-start.mdx index f9ab4741..1ebfca8d 100644 --- a/docs/01_overview/index.mdx +++ b/docs/01_introduction/quick-start.mdx @@ -1,47 +1,18 @@ --- -title: Overview -sidebar_label: Overview +title: Quick start +sidebar_label: Quick start +description: 'Get started with the Apify SDK for Python by creating your first Actor and learning the basics.' +--- + +Learn how to create and run Actors using the Apify SDK for Python. + --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. - -```py -from apify import Actor -from bs4 import BeautifulSoup -import requests - -async def main(): - async with Actor: - input = await Actor.get_input() - response = requests.get(input['url']) - soup = BeautifulSoup(response.content, 'html.parser') - await Actor.push_data({ 'url': input['url'], 'title': soup.title.string }) -``` - -## Requirements - -The Apify SDK requires Python version 3.10 or above to run Python Actors locally. - -## Installation - -The Apify Python SDK is available as [`apify`](https://pypi.org/project/apify/) package on PyPi. To install it, run: - -```bash -pip install apify -``` - -When you create an Actor using the Apify CLI, the Apify SDK for Python is installed for you automatically. - -If you are not developing Apify Actors and you just need to access the Apify API from Python, -consider using the [Apify API client for Python](/api/client/python) directly. - -## Quick start - -### Creating Actors +## Step 1: Creating Actors To create and run Actors in Apify Console, refer to the [Console documentation](/platform/actors/development/quick-start/web-ide). @@ -55,9 +26,9 @@ apify create my-first-actor --template python-start This will create a new folder called `my-first-actor`, download and extract the "Getting started with Python" Actor template there, create a virtual environment in `my-first-actor/.venv`, and install the Actor dependencies in it. -![actor create command run](../01_overview/images/apify-create.gif) +![actor create command run](./images/apify-create.gif) -#### Running the Actor +## Step 2: Running the Actor To run the Actor, you can use the [`apify run` command](/cli/docs/reference#apify-run): @@ -74,7 +45,7 @@ This command: The Actor input, for example, will be in `storage/key_value_stores/default/INPUT.json`. -## Actor structure +## Step 3: Understanding Actor structure All Python Actor templates follow the same structure. @@ -122,31 +93,6 @@ asyncio.run(main())` If you want to modify the Actor structure, you need to make sure that your Actor is executable as a module, via `python -m src`, as that is the command started by `apify run` in the Apify CLI. We recommend keeping the entrypoint for the Actor in the `src/__main__.py` file. -## Adding dependencies - -First, add the dependencies in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder. - -Then activate the virtual environment in `.venv`: - - - - { -`source .venv/bin/activate` - } - - - { -`.venv\\Scripts\\activate` - } - - - -Finally, install the dependencies: - -```bash -python -m pip install -r requirements.txt -``` - ## Next steps ### Guides diff --git a/docs/02_concepts/10_logging.mdx b/docs/02_concepts/09_logging.mdx similarity index 96% rename from docs/02_concepts/10_logging.mdx rename to docs/02_concepts/09_logging.mdx index 6bdb754b..c1bd26c6 100644 --- a/docs/02_concepts/10_logging.mdx +++ b/docs/02_concepts/09_logging.mdx @@ -5,10 +5,10 @@ title: Logging import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; -import LogConfigExample from '!!raw-loader!roa-loader!./code/10_log_config.py'; -import LoggerUsageExample from '!!raw-loader!roa-loader!./code/10_logger_usage.py'; -import RedirectLog from '!!raw-loader!roa-loader!./code/10_redirect_log.py'; -import RedirectLogExistingRun from '!!raw-loader!roa-loader!./code/10_redirect_log_existing_run.py'; +import LogConfigExample from '!!raw-loader!roa-loader!./code/09_log_config.py'; +import LoggerUsageExample from '!!raw-loader!roa-loader!./code/09_logger_usage.py'; +import RedirectLog from '!!raw-loader!roa-loader!./code/09_redirect_log.py'; +import RedirectLogExistingRun from '!!raw-loader!roa-loader!./code/09_redirect_log_existing_run.py'; The Apify SDK is logging useful information through the [`logging`](https://docs.python.org/3/library/logging.html) module from Python's standard library, into the logger with the name `apify`. diff --git a/docs/02_concepts/11_configuration.mdx b/docs/02_concepts/10_configuration.mdx similarity index 96% rename from docs/02_concepts/11_configuration.mdx rename to docs/02_concepts/10_configuration.mdx index bcc4ea00..4d1e83e8 100644 --- a/docs/02_concepts/11_configuration.mdx +++ b/docs/02_concepts/10_configuration.mdx @@ -5,7 +5,7 @@ title: Actor configuration import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; -import ConfigExample from '!!raw-loader!roa-loader!./code/11_config.py'; +import ConfigExample from '!!raw-loader!roa-loader!./code/10_config.py'; The [`Actor`](../../reference/class/Actor) class gets configured using the [`Configuration`](../../reference/class/Configuration) class, which initializes itself based on the provided environment variables. diff --git a/docs/02_concepts/12_pay_per_event.mdx b/docs/02_concepts/11_pay_per_event.mdx similarity index 97% rename from docs/02_concepts/12_pay_per_event.mdx rename to docs/02_concepts/11_pay_per_event.mdx index 1c1653b1..e51938b3 100644 --- a/docs/02_concepts/12_pay_per_event.mdx +++ b/docs/02_concepts/11_pay_per_event.mdx @@ -4,8 +4,8 @@ title: Pay-per-event monetization description: Monetize your Actors using the pay-per-event pricing model --- -import ActorChargeSource from '!!raw-loader!roa-loader!./code/12_actor_charge.py'; -import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/12_conditional_actor_charge.py'; +import ActorChargeSource from '!!raw-loader!roa-loader!./code/11_actor_charge.py'; +import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/11_conditional_actor_charge.py'; import ApiLink from '@site/src/components/ApiLink'; import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; diff --git a/docs/02_concepts/code/10_log_config.py b/docs/02_concepts/code/09_log_config.py similarity index 100% rename from docs/02_concepts/code/10_log_config.py rename to docs/02_concepts/code/09_log_config.py diff --git a/docs/02_concepts/code/10_logger_usage.py b/docs/02_concepts/code/09_logger_usage.py similarity index 100% rename from docs/02_concepts/code/10_logger_usage.py rename to docs/02_concepts/code/09_logger_usage.py diff --git a/docs/02_concepts/code/10_redirect_log.py b/docs/02_concepts/code/09_redirect_log.py similarity index 100% rename from docs/02_concepts/code/10_redirect_log.py rename to docs/02_concepts/code/09_redirect_log.py diff --git a/docs/02_concepts/code/10_redirect_log_existing_run.py b/docs/02_concepts/code/09_redirect_log_existing_run.py similarity index 100% rename from docs/02_concepts/code/10_redirect_log_existing_run.py rename to docs/02_concepts/code/09_redirect_log_existing_run.py diff --git a/docs/02_concepts/code/11_config.py b/docs/02_concepts/code/10_config.py similarity index 100% rename from docs/02_concepts/code/11_config.py rename to docs/02_concepts/code/10_config.py diff --git a/docs/02_concepts/code/12_actor_charge.py b/docs/02_concepts/code/11_actor_charge.py similarity index 100% rename from docs/02_concepts/code/12_actor_charge.py rename to docs/02_concepts/code/11_actor_charge.py diff --git a/docs/02_concepts/code/12_conditional_actor_charge.py b/docs/02_concepts/code/11_conditional_actor_charge.py similarity index 100% rename from docs/02_concepts/code/12_conditional_actor_charge.py rename to docs/02_concepts/code/11_conditional_actor_charge.py diff --git a/docs/02_concepts/09_running_webserver.mdx b/docs/03_guides/07_running_webserver.mdx similarity index 95% rename from docs/02_concepts/09_running_webserver.mdx rename to docs/03_guides/07_running_webserver.mdx index 30a80722..d9deedc1 100644 --- a/docs/02_concepts/09_running_webserver.mdx +++ b/docs/03_guides/07_running_webserver.mdx @@ -5,7 +5,7 @@ title: Running webserver in your Actor import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; -import WebserverExample from '!!raw-loader!roa-loader!./code/09_webserver.py'; +import WebserverExample from '!!raw-loader!roa-loader!./code/07_webserver.py'; Each Actor run on the Apify platform is assigned a unique hard-to-guess URL (for example `https://8segt5i81sokzm.runs.apify.net`), which enables HTTP access to an optional web server running inside the Actor run's container. diff --git a/docs/02_concepts/code/09_webserver.py b/docs/03_guides/code/07_webserver.py similarity index 100% rename from docs/02_concepts/code/09_webserver.py rename to docs/03_guides/code/07_webserver.py diff --git a/website/sidebars.js b/website/sidebars.js index b5e55e1e..6338267d 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1,8 +1,15 @@ module.exports = { sidebar: [ { - type: 'doc', - id: 'overview/index', + type: 'category', + label: 'Introduction', + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: '01_introduction', + }, + ], }, { type: 'category', From 51f781031ba65078436aeabd9e029ca102033bea Mon Sep 17 00:00:00 2001 From: patrikbraborec Date: Wed, 4 Feb 2026 14:13:12 +0100 Subject: [PATCH 2/3] docs: rename Introduction page to Overview Co-Authored-By: Claude Sonnet 4.5 (1M context) --- docs/01_introduction/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx index 2ed6344b..66bdc85e 100644 --- a/docs/01_introduction/index.mdx +++ b/docs/01_introduction/index.mdx @@ -1,7 +1,7 @@ --- id: overview -title: Introduction -sidebar_label: Introduction +title: Overview +sidebar_label: Overview description: 'The official library for creating Apify Actors in Python, providing tools for web scraping, automation, and data storage integration.' --- From d459aaeee3cb881660788563b2017795682ed221 Mon Sep 17 00:00:00 2001 From: patrikbraborec Date: Wed, 4 Feb 2026 14:36:20 +0100 Subject: [PATCH 3/3] docs: fix documentation links to use /docs/introduction path Update document ID from 'overview' to 'introduction' to align the URL path with the section name. This fixes navigation issues where the Docs button and other links were pointing to /docs/overview instead of /docs/introduction. Changes: - Change document ID in introduction page from 'overview' to 'introduction' - Update Docs navigation link in docusaurus config - Update Get Started button on homepage - Fix Documentation URL in pyproject.toml - Update README link to point to quick-start guide Co-Authored-By: Claude Sonnet 4.5 (1M context) --- README.md | 2 +- docs/01_introduction/index.mdx | 2 +- pyproject.toml | 2 +- website/docusaurus.config.js | 2 +- website/src/pages/index.js | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3187ec84..a34bacca 100644 --- a/README.md +++ b/README.md @@ -159,7 +159,7 @@ To create and run Actors through Apify Console, see the [Console documentation](https://docs.apify.com/academy/getting-started/creating-actors#choose-your-template). To create and run Python Actors locally, check the documentation for -[how to create and run Python Actors locally](https://docs.apify.com/sdk/python/docs/overview/running-locally). +[how to create and run Python Actors locally](https://docs.apify.com/sdk/python/docs/quick-start). ## Guides diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx index 66bdc85e..3303b0d1 100644 --- a/docs/01_introduction/index.mdx +++ b/docs/01_introduction/index.mdx @@ -1,5 +1,5 @@ --- -id: overview +id: introduction title: Overview sidebar_label: Overview description: 'The official library for creating Apify Actors in Python, providing tools for web scraping, automation, and data storage integration.' diff --git a/pyproject.toml b/pyproject.toml index f87a9a89..1a9abf77 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,7 +56,7 @@ scrapy = ["scrapy>=2.11.0"] "Apify Homepage" = "https://apify.com" "Changelog" = "https://docs.apify.com/sdk/python/docs/changelog" "Discord" = "https://discord.com/invite/jyEM2PRvMU" -"Documentation" = "https://docs.apify.com/sdk/python/docs/overview/introduction" +"Documentation" = "https://docs.apify.com/sdk/python/docs/introduction" "Homepage" = "https://docs.apify.com/sdk/python/" "Issue Tracker" = "https://github.com/apify/apify-sdk-python/issues" "Release Notes" = "https://docs.apify.com/sdk/python/docs/upgrading/upgrading-to-v2" diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 8cf423ce..66f71a9b 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -66,7 +66,7 @@ module.exports = { title: 'SDK for Python', items: [ { - to: 'docs/overview', + to: 'docs/introduction', label: 'Docs', position: 'left', activeBaseRegex: '/docs(?!/changelog)', diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 3ac15db1..f9261ba0 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -35,7 +35,7 @@ function Hero() {
- Get Started + Get Started