Skip to content

Commit 23d3db6

Browse files
authored
docs: use the common ApiLink component from the shared theme (#900)
Uses the common `ApiLink` implementation from the shared theme package. Closes #889
1 parent 8441a83 commit 23d3db6

27 files changed

Lines changed: 54 additions & 59 deletions

docs/02_concepts/01_actor_lifecycle.mdx

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ description: How an Apify Actor starts, runs, and shuts down, including context
77
import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88
import Tabs from '@theme/Tabs';
99
import TabItem from '@theme/TabItem';
10+
import ApiLink from '@theme/ApiLink';
1011

1112
import ClassContextExample from '!!raw-loader!roa-loader!./code/01_class_context.py';
1213
import ClassManualExample from '!!raw-loader!roa-loader!./code/01_class_manual.py';
@@ -26,7 +27,7 @@ This guide explains how an **Apify Actor** starts, runs, and shuts down, describ
2627

2728
During initialization, the SDK prepares all the components required to integrate with the Apify platform. It loads configuration from environment variables, initializes access to platform storages such as the [key-value store, dataset, and request queue](https://docs.apify.com/platform/storage), sets up event handling for [platform events](https://docs.apify.com/platform/integrations/webhooks/events), and configures logging.
2829

29-
The recommended approach in Python is to use the global [`Actor`](https://docs.apify.com/sdk/python/reference/class/Actor) class as an asynchronous context manager. This approach automatically manages setup and teardown and keeps your code concise. When entering the context, the SDK loads configuration and initializes clients lazily—for example, a dataset is opened only when it is first accessed. If the Actor runs on the Apify platform, it also begins listening for platform events.
30+
The recommended approach in Python is to use the global <ApiLink to="class/Actor">`Actor`</ApiLink> class as an asynchronous context manager. This approach automatically manages setup and teardown and keeps your code concise. When entering the context, the SDK loads configuration and initializes clients lazily—for example, a dataset is opened only when it is first accessed. If the Actor runs on the Apify platform, it also begins listening for platform events.
3031

3132
When the Actor exits, either normally or due to an exception, the SDK performs a graceful shutdown. It persists the final Actor state, stops event handling, and sets the terminal exit code together with the [status message](https://docs.apify.com/platform/actors/development/programming-interface/status-messages).
3233

@@ -43,9 +44,9 @@ When the Actor exits, either normally or due to an exception, the SDK performs a
4344
</TabItem>
4445
</Tabs>
4546

46-
You can also create an [`Actor`](https://docs.apify.com/sdk/python/reference/class/Actor) instance directly. This does not change its capabilities but allows you to specify optional parameters during initialization. The key parameters are:
47+
You can also create an <ApiLink to="class/Actor">`Actor`</ApiLink> instance directly. This does not change its capabilities but allows you to specify optional parameters during initialization. The key parameters are:
4748

48-
- `configuration` — a custom [`Configuration`](https://docs.apify.com/sdk/python/reference/class/Configuration) instance to control storage paths, API URLs, and other settings.
49+
- `configuration` — a custom <ApiLink to="class/Configuration">`Configuration`</ApiLink> instance to control storage paths, API URLs, and other settings.
4950
- `configure_logging` — whether to set up default logging configuration (default `True`). Set to `False` if you configure logging yourself.
5051
- `exit_process` — whether the Actor calls `sys.exit()` when the context manager exits. Defaults to `True`, except in IPython, Pytest, and Scrapy environments.
5152
- `event_listeners_timeout` — maximum time to wait for Actor event listeners to complete before exiting.
@@ -72,18 +73,18 @@ Good error handling lets your Actor fail fast on critical errors, retry transien
7273

7374
The SDK provides helper methods for explicit control:
7475

75-
- [`Actor.exit`](https://docs.apify.com/sdk/python/reference/class/Actor#exit) - terminates the run successfully (default exit code 0).
76-
- [`Actor.fail`](https://docs.apify.com/sdk/python/reference/class/Actor#fail) - marks the run as failed (default exit code 1).
76+
- <ApiLink to="class/Actor#exit">`Actor.exit`</ApiLink> - terminates the run successfully (default exit code 0).
77+
- <ApiLink to="class/Actor#fail">`Actor.fail`</ApiLink> - marks the run as failed (default exit code 1).
7778

7879
Any non-zero exit code is treated as a `FAILED` run. You rarely need to call these methods directly unless you want to perform a controlled shutdown or customize the exit behavior.
7980

80-
Catch exceptions only when necessary - for example, to retry network timeouts or map specific errors to exit codes. Keep retry loops bounded with backoff and re-raise once exhausted. Make your processing idempotent so that restarts don't corrupt results. Both [`Actor.exit`](https://docs.apify.com/sdk/python/reference/class/Actor#exit) and [`Actor.fail`](https://docs.apify.com/sdk/python/reference/class/Actor#fail) perform the same cleanup, so complete any long-running persistence before calling them.
81+
Catch exceptions only when necessary - for example, to retry network timeouts or map specific errors to exit codes. Keep retry loops bounded with backoff and re-raise once exhausted. Make your processing idempotent so that restarts don't corrupt results. Both <ApiLink to="class/Actor#exit">`Actor.exit`</ApiLink> and <ApiLink to="class/Actor#fail">`Actor.fail`</ApiLink> perform the same cleanup, so complete any long-running persistence before calling them.
8182

8283
Below is a minimal context-manager example where an unhandled exception automatically fails the run, followed by a manual pattern giving you more control.
8384

8485
<RunnableCodeBlock className="language-python" language="python">{ErrorHandlingContextExample}</RunnableCodeBlock>
8586

86-
If you need explicit control over exit codes or status messages, you can manage the Actor manually using [`Actor.init`](https://docs.apify.com/sdk/python/reference/class/Actor#init), [`Actor.exit`](https://docs.apify.com/sdk/python/reference/class/Actor#exit), and [`Actor.fail`](https://docs.apify.com/sdk/python/reference/class/Actor#fail).
87+
If you need explicit control over exit codes or status messages, you can manage the Actor manually using <ApiLink to="class/Actor#init">`Actor.init`</ApiLink>, <ApiLink to="class/Actor#exit">`Actor.exit`</ApiLink>, and <ApiLink to="class/Actor#fail">`Actor.fail`</ApiLink>.
8788

8889
<RunnableCodeBlock className="language-python" language="python">{ErrorHandlingManualExample}</RunnableCodeBlock>
8990

@@ -105,4 +106,4 @@ Update the status only when the user's understanding of progress changes - avoid
105106

106107
## Conclusion
107108

108-
This page has presented the full Actor lifecycle: initialization, execution, error handling, rebooting, shutdown and status messages. You've seen how the SDK supports both context-based and manual control patterns. For deeper dives, explore the [reference docs](https://docs.apify.com/sdk/python/reference), [guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx), and [platform documentation](https://docs.apify.com/platform).
109+
This page has presented the full Actor lifecycle: initialization, execution, error handling, rebooting, shutdown and status messages. You've seen how the SDK supports both context-based and manual control patterns. For deeper dives, explore the <ApiLink to="">reference docs</ApiLink>, [guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx), and [platform documentation](https://docs.apify.com/platform).

docs/02_concepts/02_actor_input.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88

99
import InputExample from '!!raw-loader!roa-loader!./code/02_input.py';
1010
import RequestListExample from '!!raw-loader!roa-loader!./code/02_request_list.py';
11-
import ApiLink from '@site/src/components/ApiLink';
11+
import ApiLink from '@theme/ApiLink';
1212

1313
The Actor gets its [input](https://docs.apify.com/platform/actors/running/input) from the input record in its default [key-value store](https://docs.apify.com/platform/storage/key-value-store).
1414

docs/02_concepts/03_storages.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88

99
import OpeningStoragesExample from '!!raw-loader!roa-loader!./code/03_opening_storages.py';
1010
import OpeningStoragesAliasExample from '!!raw-loader!roa-loader!./code/03_opening_storages_alias.py';
11-
import ApiLink from '@site/src/components/ApiLink';
11+
import ApiLink from '@theme/ApiLink';
1212
import DeletingStoragesExample from '!!raw-loader!roa-loader!./code/03_deleting_storages.py';
1313
import DatasetReadWriteExample from '!!raw-loader!roa-loader!./code/03_dataset_read_write.py';
1414
import DatasetExportsExample from '!!raw-loader!roa-loader!./code/03_dataset_exports.py';

docs/02_concepts/04_actor_events.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88

99
import ActorEventsExample from '!!raw-loader!roa-loader!./code/04_actor_events.py';
1010
import UseStateExample from '!!raw-loader!roa-loader!./code/04_use_state.py';
11-
import ApiLink from '@site/src/components/ApiLink';
11+
import ApiLink from '@theme/ApiLink';
1212

1313
During its runtime, the Actor receives Actor events sent by the Apify platform or generated by the Apify SDK itself.
1414

docs/02_concepts/05_proxy_management.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import CustomProxyFunctionExample from '!!raw-loader!roa-loader!./code/05_custom
1414
import ProxyActorInputExample from '!!raw-loader!roa-loader!./code/05_proxy_actor_input.py';
1515
import ProxyHttpxExample from '!!raw-loader!roa-loader!./code/05_proxy_httpx.py';
1616
import TieredProxyExample from '!!raw-loader!roa-loader!./code/05_tiered_proxy.py';
17-
import ApiLink from '@site/src/components/ApiLink';
17+
import ApiLink from '@theme/ApiLink';
1818

1919
The Apify SDK provides built-in proxy management through the <ApiLink to="class/ProxyConfiguration">`ProxyConfiguration`</ApiLink> class, supporting both [Apify Proxy](https://apify.com/proxy) and custom proxy servers. Proxies are essential for web scraping to avoid [IP address blocking](https://en.wikipedia.org/wiki/IP_address_blocking) and distribute requests across multiple addresses.
2020

docs/02_concepts/06_interacting_with_other_actors.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import InteractingCallExample from '!!raw-loader!roa-loader!./code/06_interactin
1111
import InteractingCallTaskExample from '!!raw-loader!roa-loader!./code/06_interacting_call_task.py';
1212
import InteractingMetamorphExample from '!!raw-loader!roa-loader!./code/06_interacting_metamorph.py';
1313
import InteractingAbortExample from '!!raw-loader!roa-loader!./code/06_interacting_abort.py';
14-
import ApiLink from '@site/src/components/ApiLink';
14+
import ApiLink from '@theme/ApiLink';
1515

1616
The Apify SDK lets you start, call, and transform (metamorph) other Actors directly from your Actor code. This is useful for composing complex workflows from smaller, reusable Actors.
1717

docs/02_concepts/07_webhooks.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Set up webhooks to trigger actions when Actor run events occur.
66

77
import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88

9-
import ApiLink from '@site/src/components/ApiLink';
9+
import ApiLink from '@theme/ApiLink';
1010
import WebhookExample from '!!raw-loader!roa-loader!./code/07_webhook.py';
1111
import WebhookPreventingExample from '!!raw-loader!roa-loader!./code/07_webhook_preventing.py';
1212

docs/02_concepts/08_access_apify_api.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Use the built-in Apify API client to access platform features not c
66

77
import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88

9-
import ApiLink from '@site/src/components/ApiLink';
9+
import ApiLink from '@theme/ApiLink';
1010
import ActorClientExample from '!!raw-loader!roa-loader!./code/08_actor_client.py';
1111
import ActorNewClientExample from '!!raw-loader!roa-loader!./code/08_actor_new_client.py';
1212

docs/02_concepts/09_logging.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Configure log levels, formatting, and log redirection between Actor
66

77
import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
88

9-
import ApiLink from '@site/src/components/ApiLink';
9+
import ApiLink from '@theme/ApiLink';
1010
import LogConfigExample from '!!raw-loader!roa-loader!./code/09_log_config.py';
1111
import LoggerUsageExample from '!!raw-loader!roa-loader!./code/09_logger_usage.py';
1212
import RedirectLog from '!!raw-loader!roa-loader!./code/09_redirect_log.py';

docs/02_concepts/10_configuration.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
99
import ConfigExample from '!!raw-loader!roa-loader!./code/10_config.py';
1010
import GetEnvExample from '!!raw-loader!roa-loader!./code/10_get_env.py';
1111
import PlatformDetectionExample from '!!raw-loader!roa-loader!./code/10_platform_detection.py';
12-
import ApiLink from '@site/src/components/ApiLink';
12+
import ApiLink from '@theme/ApiLink';
1313

1414
The <ApiLink to="class/Actor">`Actor`</ApiLink> class is configured through the <ApiLink to="class/Configuration">`Configuration`</ApiLink> class, which reads its settings from environment variables. When running on the Apify platform or through the Apify CLI, configuration is automatic — manual setup is only needed for custom requirements.
1515

0 commit comments

Comments
 (0)