docs: Improve API doc groups and polish docstrings (#638)

## Summary

- Introduces the `@docs_group()` decorator (following the crawlee-python
pattern) to organize all public symbols into clear documentation groups:
**Apify API clients**, **Resource clients**, **HTTP clients**,
**Models**, and **Errors**
- Applies the decorator to all 260+ public classes across the codebase
(2 API clients, 61 resource clients, 192 models, 2 HTTP clients, 3
errors)
- Updates `website/transformDocs.js` to read group assignments from the
decorator instead of hardcoded JS predicates
- Improves and polishes all docstrings for Apify API clients, Resource
clients, HTTP clients, and Errors with consistent patterns and helpful
context

## Screenshot

<img width="2880" height="6778" alt="image"
src="https://github.com/user-attachments/assets/b4b101e8-6a6d-47a4-b096-04eff0267460"
/>

## Issues

- Closes: #637

## Test plan

- [x] CI passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: vdusek

src/apify_client/_apify_client.py

@@ -43,12 +43,8 @@
         ScheduleClientAsync,
         ScheduleCollectionClient,
         ScheduleCollectionClientAsync,
-        StatusMessageWatcherAsync,
-        StatusMessageWatcherSync,
         StoreCollectionClient,
         StoreCollectionClientAsync,
-        StreamedLogAsync,
-        StreamedLogSync,
         TaskClient,
         TaskClientAsync,
         TaskCollectionClient,
@@ -87,8 +83,6 @@ class ClientRegistry:
     key_value_store_client: type[KeyValueStoreClient]
     key_value_store_collection_client: type[KeyValueStoreCollectionClient]
     log_client: type[LogClient]
-    status_message_watcher: type[StatusMessageWatcherSync]
-    streamed_log: type[StreamedLogSync]
     request_queue_client: type[RequestQueueClient]
     request_queue_collection_client: type[RequestQueueCollectionClient]
     run_client: type[RunClient]
@@ -126,8 +120,6 @@ class ClientRegistryAsync:
     key_value_store_client: type[KeyValueStoreClientAsync]
     key_value_store_collection_client: type[KeyValueStoreCollectionClientAsync]
     log_client: type[LogClientAsync]
-    status_message_watcher: type[StatusMessageWatcherAsync]
-    streamed_log: type[StreamedLogAsync]
     request_queue_client: type[RequestQueueClientAsync]
     request_queue_collection_client: type[RequestQueueCollectionClientAsync]
     run_client: type[RunClientAsync]

src/apify_client/_client_registry.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal, TypeVar
+
+# The order of the rendered API groups is defined by GROUP_ORDER in website/transformDocs.js
+# and applied via groupSort in website/docusaurus.config.js.
+GroupName = Literal[
+    'Apify API clients',
+    'HTTP clients',
+    'Resource clients',
+    'Errors',
+    'Models',
+    'Other',
+]
+
+T = TypeVar('T', bound=Callable[..., Any])
+
+
+def docs_group(group_name: GroupName) -> Callable[[T], T]:  # noqa: ARG001
+    """Mark a symbol for rendering and grouping in documentation.
+
+    This decorator is used solely for documentation purposes and does not modify the behavior
+    of the decorated callable.
+
+    Args:
+        group_name: The documentation group to which the symbol belongs.
+
+    Returns:
+        The original callable without modification.
+    """
+
+    def wrapper(func: T) -> T:
+        return func
+
+    return wrapper

src/apify_client/_docs.py

@@ -11,6 +11,7 @@
 import impit
 
 from apify_client._consts import DEFAULT_MAX_RETRIES, DEFAULT_MIN_DELAY_BETWEEN_RETRIES, DEFAULT_TIMEOUT
+from apify_client._docs import docs_group
 from apify_client._http_clients._base import BaseHttpClient
 from apify_client._logging import log_context, logger_name
 from apify_client._utils import to_seconds
@@ -27,8 +28,14 @@
 logger = logging.getLogger(logger_name)
 
 
+@docs_group('HTTP clients')
 class HttpClient(BaseHttpClient):
-    """Synchronous HTTP client for Apify API with automatic retries and exponential backoff."""
+    """Synchronous HTTP client for the Apify API.
+
+    Handles authentication, request serialization, and automatic retries with exponential backoff
+    for rate-limited (HTTP 429) and server error (HTTP 5xx) responses. Non-retryable errors
+    (e.g. HTTP 4xx client errors) are raised immediately.
+    """
 
     def __init__(
         self,
@@ -44,9 +51,9 @@ def __init__(
 
         Args:
             token: Apify API token for authentication.
-            timeout: Request timeout.
-            max_retries: Maximum number of retries for failed requests.
-            min_delay_between_retries: Minimum delay between retries.
+            timeout: Default timeout for HTTP requests.
+            max_retries: Maximum number of retry attempts for failed requests.
+            min_delay_between_retries: Minimum delay between retries (increases exponentially with each attempt).
             statistics: Statistics tracker for API calls. Created automatically if not provided.
             headers: Additional HTTP headers to include in all requests.
         """
@@ -247,8 +254,14 @@ def stop_retrying() -> None:
         return func(stop_retrying, max_retries + 1)
 
 
+@docs_group('HTTP clients')
 class HttpClientAsync(BaseHttpClient):
-    """Asynchronous HTTP client for Apify API with automatic retries and exponential backoff."""
+    """Asynchronous HTTP client for the Apify API.
+
+    Handles authentication, request serialization, and automatic retries with exponential backoff
+    for rate-limited (HTTP 429) and server error (HTTP 5xx) responses. Non-retryable errors
+    (e.g. HTTP 4xx client errors) are raised immediately.
+    """
 
     def __init__(
         self,
@@ -264,9 +277,9 @@ def __init__(
 
         Args:
             token: Apify API token for authentication.
-            timeout: Request timeout.
-            max_retries: Maximum number of retries for failed requests.
-            min_delay_between_retries: Minimum delay between retries.
+            timeout: Default timeout for HTTP requests.
+            max_retries: Maximum number of retry attempts for failed requests.
+            min_delay_between_retries: Minimum delay between retries (increases exponentially with each attempt).
             statistics: Statistics tracker for API calls. Created automatically if not provided.
             headers: Additional HTTP headers to include in all requests.
         """

src/apify_client/_http_clients/_http_client.py

@@ -17,9 +17,7 @@
 from .run_collection import RunCollectionClient, RunCollectionClientAsync
 from .schedule import ScheduleClient, ScheduleClientAsync
 from .schedule_collection import ScheduleCollectionClient, ScheduleCollectionClientAsync
-from .status_message_watcher import StatusMessageWatcher, StatusMessageWatcherAsync, StatusMessageWatcherSync
 from .store_collection import StoreCollectionClient, StoreCollectionClientAsync
-from .streamed_log import StreamedLog, StreamedLogAsync, StreamedLogSync
 from .task import TaskClient, TaskClientAsync
 from .task_collection import TaskCollectionClient, TaskCollectionClientAsync
 from .user import UserClient, UserClientAsync
@@ -67,14 +65,8 @@
     'ScheduleClientAsync',
     'ScheduleCollectionClient',
     'ScheduleCollectionClientAsync',
-    'StatusMessageWatcher',
-    'StatusMessageWatcherAsync',
-    'StatusMessageWatcherSync',
     'StoreCollectionClient',
     'StoreCollectionClientAsync',
-    'StreamedLog',
-    'StreamedLogAsync',
-    'StreamedLogSync',
     'TaskClient',
     'TaskClientAsync',
     'TaskCollectionClient',

src/apify_client/_resource_clients/__init__.py

@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING, Any
 
 from apify_client._consts import DEFAULT_WAIT_FOR_FINISH, DEFAULT_WAIT_WHEN_JOB_NOT_EXIST, TERMINAL_STATUSES
+from apify_client._docs import docs_group
 from apify_client._internal_models import ActorJobResponse
 from apify_client._logging import WithLogDetailsClient
 from apify_client._utils import catch_not_found_or_throw, response_to_dict, to_safe_id, to_seconds
@@ -120,6 +121,7 @@ def _build_params(self, **kwargs: Any) -> dict:
         return {k: v for k, v in merged.items() if v is not None}
 
 
+@docs_group('Resource clients')
 class ResourceClient(ResourceClientBase):
     """Base class for synchronous resource clients."""
 
@@ -286,6 +288,7 @@ def _wait_for_finish(
         return actor_job
 
 
+@docs_group('Resource clients')
 class ResourceClientAsync(ResourceClientBase):
     """Base class for asynchronous resource clients."""
 

src/apify_client/_resource_clients/_resource_client.py

@@ -2,6 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, Literal
 
+from apify_client._docs import docs_group
 from apify_client._models import (
     Actor,
     ActorPermissionLevel,
@@ -47,8 +48,13 @@
     )
 
 
+@docs_group('Resource clients')
 class ActorClient(ResourceClient):
-    """Sub-client for manipulating a single Actor."""
+    """Sub-client for managing a specific Actor.
+
+    Provides methods to manage a specific Actor, e.g. update it, delete it, build it, or start runs. Obtain an instance
+    via an appropriate method on the `ApifyClient` class.
+    """
 
     def __init__(
         self,
@@ -506,8 +512,13 @@ def validate_input(
         return True
 
 
+@docs_group('Resource clients')
 class ActorClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating a single Actor."""
+    """Sub-client for managing a specific Actor.
+
+    Provides methods to manage a specific Actor, e.g. update it, delete it, build it, or start runs. Obtain an instance
+    via an appropriate method on the `ApifyClientAsync` class.
+    """
 
     def __init__(
         self,

src/apify_client/_resource_clients/actor.py

@@ -2,6 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, Literal
 
+from apify_client._docs import docs_group
 from apify_client._models import Actor, ActorResponse, ListOfActors, ListOfActorsResponse
 from apify_client._representations import get_actor_repr
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
@@ -11,8 +12,13 @@
     from datetime import timedelta
 
 
+@docs_group('Resource clients')
 class ActorCollectionClient(ResourceClient):
-    """Sub-client for manipulating Actors."""
+    """Sub-client for the Actor collection.
+
+    Provides methods to manage the Actor collection, e.g. list or create Actors. Obtain an instance via an appropriate
+    method on the `ApifyClient` class.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'acts')
@@ -138,8 +144,13 @@ def create(
         return ActorResponse.model_validate(result).data
 
 
+@docs_group('Resource clients')
 class ActorCollectionClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating Actors."""
+    """Sub-client for the Actor collection.
+
+    Provides methods to manage the Actor collection, e.g. list or create Actors. Obtain an instance via an appropriate
+    method on the `ApifyClientAsync` class.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'acts')

src/apify_client/_resource_clients/actor_collection.py

@@ -2,6 +2,7 @@
 
 from typing import Any
 
+from apify_client._docs import docs_group
 from apify_client._models import EnvVar, EnvVarResponse
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._utils import filter_none_values
@@ -21,8 +22,13 @@ def get_actor_env_var_representation(
     }
 
 
+@docs_group('Resource clients')
 class ActorEnvVarClient(ResourceClient):
-    """Sub-client for manipulating a single Actor environment variable."""
+    """Sub-client for managing a specific Actor environment variable.
+
+    Provides methods to manage a specific Actor environment variable, e.g. get, update, or delete it. Obtain an instance
+    via an appropriate method on the `ActorVersionClient` class.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')
@@ -77,8 +83,13 @@ def delete(self) -> None:
         self._delete()
 
 
+@docs_group('Resource clients')
 class ActorEnvVarClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating a single Actor environment variable."""
+    """Sub-client for managing a specific Actor environment variable.
+
+    Provides methods to manage a specific Actor environment variable, e.g. get, update, or delete it. Obtain an instance
+    via an appropriate method on the `ActorVersionClientAsync` class.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')

src/apify_client/_resource_clients/actor_env_var.py

@@ -2,14 +2,20 @@
 
 from typing import Any
 
+from apify_client._docs import docs_group
 from apify_client._models import EnvVar, EnvVarResponse, ListOfEnvVars, ListOfEnvVarsResponse
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._resource_clients.actor_env_var import get_actor_env_var_representation
 from apify_client._utils import filter_none_values
 
 
+@docs_group('Resource clients')
 class ActorEnvVarCollectionClient(ResourceClient):
-    """Sub-client for manipulating Actor env vars."""
+    """Sub-client for the Actor environment variable collection.
+
+    Provides methods to manage Actor environment variables, e.g. list or create them. Obtain an instance via an
+    appropriate method on the `ActorVersionClient` class.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')
@@ -55,8 +61,13 @@ def create(
         return EnvVarResponse.model_validate(result).data
 
 
+@docs_group('Resource clients')
 class ActorEnvVarCollectionClientAsync(ResourceClientAsync):
-    """Async sub-client for manipulating Actor env vars."""
+    """Sub-client for the Actor environment variable collection.
+
+    Provides methods to manage Actor environment variables, e.g. list or create them. Obtain an instance via an
+    appropriate method on the `ActorVersionClientAsync` class.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         resource_path = kwargs.pop('resource_path', 'env-vars')