Skip to content

Commit 3966ec0

Browse files
vdusekclaude
andcommitted
docs: Improve API reference with docs_group decorator
Add @docs_group decorator to organize public symbols into clear documentation sections (Apify API clients, Resource clients, HTTP clients, Models, Errors) instead of generic predicate-based grouping. Update transformDocs.js to read group names from the decorator. Closes #637 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 7895a4e commit 3966ec0

35 files changed

Lines changed: 366 additions & 15 deletions

‎src/apify_client/_apify_client.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
1313
DEFAULT_TIMEOUT,
1414
)
15+
from apify_client._docs import docs_group
1516
from apify_client._http_clients import HttpClient, HttpClientAsync
1617
from apify_client._resource_clients import (
1718
ActorClient,
@@ -79,6 +80,7 @@
7980
from datetime import timedelta
8081

8182

83+
@docs_group('Apify API clients')
8284
class ApifyClient:
8385
"""The Apify API client."""
8486

@@ -340,6 +342,7 @@ def store(self) -> StoreCollectionClient:
340342
return StoreCollectionClient(**self._base_kwargs)
341343

342344

345+
@docs_group('Apify API clients')
343346
class ApifyClientAsync:
344347
"""The asynchronous version of the Apify API client."""
345348

‎src/apify_client/_docs.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
from __future__ import annotations
2+
3+
from collections.abc import Callable
4+
from typing import Any, Literal, TypeVar
5+
6+
# The order of the rendered API groups is defined in the website/docusaurus.config.js file.
7+
GroupName = Literal[
8+
'Apify API clients',
9+
'Resource clients',
10+
'HTTP clients',
11+
'Models',
12+
'Errors',
13+
]
14+
15+
T = TypeVar('T', bound=Callable[..., Any])
16+
17+
18+
def docs_group(group_name: GroupName) -> Callable[[T], T]: # noqa: ARG001
19+
"""Mark a symbol for rendering and grouping in documentation.
20+
21+
This decorator is used solely for documentation purposes and does not modify the behavior
22+
of the decorated callable.
23+
24+
Args:
25+
group_name: The documentation group to which the symbol belongs.
26+
27+
Returns:
28+
The original callable without modification.
29+
"""
30+
31+
def wrapper(func: T) -> T:
32+
return func
33+
34+
return wrapper

‎src/apify_client/_http_clients/_http_client.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import impit
1212

1313
from apify_client._consts import DEFAULT_MAX_RETRIES, DEFAULT_MIN_DELAY_BETWEEN_RETRIES, DEFAULT_TIMEOUT
14+
from apify_client._docs import docs_group
1415
from apify_client._http_clients._base import BaseHttpClient
1516
from apify_client._logging import log_context, logger_name
1617
from apify_client._utils import to_seconds
@@ -27,6 +28,7 @@
2728
logger = logging.getLogger(logger_name)
2829

2930

31+
@docs_group('HTTP clients')
3032
class HttpClient(BaseHttpClient):
3133
"""Synchronous HTTP client for Apify API with automatic retries and exponential backoff."""
3234

@@ -247,6 +249,7 @@ def stop_retrying() -> None:
247249
return func(stop_retrying, max_retries + 1)
248250

249251

252+
@docs_group('HTTP clients')
250253
class HttpClientAsync(BaseHttpClient):
251254
"""Asynchronous HTTP client for Apify API with automatic retries and exponential backoff."""
252255

0 commit comments

Comments
 (0)