docs: Improve API doc groups

vdusek · vdusek · commit 7987324f9b56 · 2025-07-22T11:43:33.000+02:00
Closes: #508
diff --git a/src/apify/_actor.py b/src/apify/_actor.py
@@ -54,7 +54,7 @@
 
 
 @docs_name('Actor')
-@docs_group('Classes')
+@docs_group('Actor')
 class _ActorType:
     """The class of `Actor`. Only make a new instance if you're absolutely sure you need to."""
 
diff --git a/src/apify/_charging.py b/src/apify/_charging.py
@@ -26,7 +26,7 @@
 run_validator = TypeAdapter[ActorRun | None](ActorRun | None)
 
 
-@docs_group('Interfaces')
+@docs_group('Charging')
 class ChargingManager(Protocol):
     """Provides fine-grained access to pay-per-event functionality."""
 
@@ -57,7 +57,7 @@ def get_pricing_info(self) -> ActorPricingInfo:
         """
 
 
-@docs_group('Data structures')
+@docs_group('Charging')
 @dataclass(frozen=True)
 class ChargeResult:
     """Result of the `ChargingManager.charge` method."""
@@ -72,7 +72,7 @@ class ChargeResult:
     """How many events of each known type can still be charged within the limit."""
 
 
-@docs_group('Data structures')
+@docs_group('Charging')
 @dataclass
 class ActorPricingInfo:
     """Result of the `ChargingManager.get_pricing_info` method."""
diff --git a/src/apify/_configuration.py b/src/apify/_configuration.py
@@ -25,7 +25,7 @@ def _transform_to_list(value: Any) -> list[str] | None:
     return value if isinstance(value, list) else str(value).split(',')
 
 
-@docs_group('Classes')
+@docs_group('Configuration')
 class Configuration(CrawleeConfiguration):
     """A class for specifying the configuration of an Actor.
 
diff --git a/src/apify/_models.py b/src/apify/_models.py
@@ -16,7 +16,7 @@
     from typing import TypeAlias
 
 
-@docs_group('Data structures')
+@docs_group('Actor')
 class Webhook(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -35,14 +35,14 @@ class Webhook(BaseModel):
     ] = None
 
 
-@docs_group('Data structures')
+@docs_group('Actor')
 class ActorRunMeta(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
     origin: Annotated[MetaOrigin, Field()]
 
 
-@docs_group('Data structures')
+@docs_group('Actor')
 class ActorRunStats(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -63,7 +63,7 @@ class ActorRunStats(BaseModel):
     compute_units: Annotated[float, Field(alias='computeUnits')]
 
 
-@docs_group('Data structures')
+@docs_group('Actor')
 class ActorRunOptions(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -74,7 +74,7 @@ class ActorRunOptions(BaseModel):
     max_total_charge_usd: Annotated[Decimal | None, Field(alias='maxTotalChargeUsd')] = None
 
 
-@docs_group('Data structures')
+@docs_group('Actor')
 class ActorRunUsage(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -92,7 +92,7 @@ class ActorRunUsage(BaseModel):
     proxy_serps: Annotated[float | None, Field(alias='PROXY_SERPS')] = None
 
 
-@docs_group('Data structures')
+@docs_group('Actor')
 class ActorRun(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
diff --git a/src/apify/_platform_event_manager.py b/src/apify/_platform_event_manager.py
@@ -27,17 +27,10 @@
 
     from apify._configuration import Configuration
 
-
 __all__ = ['EventManager', 'LocalEventManager', 'PlatformEventManager']
 
 
-@docs_group('Data structures')
-class PersistStateEvent(BaseModel):
-    name: Literal[Event.PERSIST_STATE]
-    data: Annotated[EventPersistStateData, Field(default_factory=lambda: EventPersistStateData(is_migrating=False))]
-
-
-@docs_group('Data structures')
+@docs_group('Event data')
 class SystemInfoEventData(BaseModel):
     mem_avg_bytes: Annotated[float, Field(alias='memAvgBytes')]
     mem_current_bytes: Annotated[float, Field(alias='memCurrentBytes')]
@@ -64,31 +57,37 @@ def to_crawlee_format(self, dedicated_cpus: float) -> EventSystemInfoData:
         )
 
 
-@docs_group('Data structures')
+@docs_group('Events')
+class PersistStateEvent(BaseModel):
+    name: Literal[Event.PERSIST_STATE]
+    data: Annotated[EventPersistStateData, Field(default_factory=lambda: EventPersistStateData(is_migrating=False))]
+
+
+@docs_group('Events')
 class SystemInfoEvent(BaseModel):
     name: Literal[Event.SYSTEM_INFO]
     data: SystemInfoEventData
 
 
-@docs_group('Data structures')
+@docs_group('Events')
 class MigratingEvent(BaseModel):
     name: Literal[Event.MIGRATING]
     data: Annotated[EventMigratingData, Field(default_factory=EventMigratingData)]
 
 
-@docs_group('Data structures')
+@docs_group('Events')
 class AbortingEvent(BaseModel):
     name: Literal[Event.ABORTING]
     data: Annotated[EventAbortingData, Field(default_factory=EventAbortingData)]
 
 
-@docs_group('Data structures')
+@docs_group('Events')
 class ExitEvent(BaseModel):
     name: Literal[Event.EXIT]
     data: Annotated[EventExitData, Field(default_factory=EventExitData)]
 
 
-@docs_group('Data structures')
+@docs_group('Events')
 class EventWithoutData(BaseModel):
     name: Literal[
         Event.SESSION_RETIRED,
@@ -101,13 +100,13 @@ class EventWithoutData(BaseModel):
     data: Any = None
 
 
-@docs_group('Data structures')
+@docs_group('Events')
 class DeprecatedEvent(BaseModel):
     name: Literal['cpuInfo']
     data: Annotated[dict[str, Any], Field(default_factory=dict)]
 
 
-@docs_group('Data structures')
+@docs_group('Events')
 class UnknownEvent(BaseModel):
     name: str
     data: Annotated[dict[str, Any], Field(default_factory=dict)]
@@ -120,7 +119,7 @@ class UnknownEvent(BaseModel):
 )
 
 
-@docs_group('Classes')
+@docs_group('Event managers')
 class PlatformEventManager(EventManager):
     """A class for managing Actor events.
 
diff --git a/src/apify/_proxy_configuration.py b/src/apify/_proxy_configuration.py
@@ -69,7 +69,7 @@ def _check(
         raise ValueError(f'{error_str} does not match pattern {pattern.pattern!r}')
 
 
-@docs_group('Classes')
+@docs_group('Configuration')
 @dataclass
 class ProxyInfo(CrawleeProxyInfo):
     """Provides information about a proxy connection that is used for requests."""
@@ -89,7 +89,7 @@ class ProxyInfo(CrawleeProxyInfo):
     """
 
 
-@docs_group('Classes')
+@docs_group('Configuration')
 class ProxyConfiguration(CrawleeProxyConfiguration):
     """Configures a connection to a proxy server with the provided options.
 
diff --git a/src/apify/_utils.py b/src/apify/_utils.py
@@ -30,7 +30,19 @@ def is_running_in_ipython() -> bool:
     return getattr(builtins, '__IPYTHON__', False)
 
 
-GroupName = Literal['Classes', 'Abstract classes', 'Interfaces', 'Data structures', 'Errors', 'Functions']
+# The order of the rendered API groups is defined in the website/docusaurus.config.js file.
+GroupName = Literal[
+    'Actor',
+    'Charging',
+    'Configuration',
+    'Event managers',
+    'Events',
+    'Event data',
+    'Request loaders',
+    'Storage clients',
+    'Storage data',
+    'Storages',
+]
 
 
 def docs_group(group_name: GroupName) -> Callable:  # noqa: ARG001
diff --git a/src/apify/apify_storage_client/_apify_storage_client.py b/src/apify/apify_storage_client/_apify_storage_client.py
@@ -20,7 +20,7 @@
     from apify._configuration import Configuration
 
 
-@docs_group('Classes')
+@docs_group('Storage clients')
 class ApifyStorageClient(StorageClient):
     """A storage client implementation based on the Apify platform storage."""
 
diff --git a/src/apify/storages/_request_list.py b/src/apify/storages/_request_list.py
@@ -38,7 +38,7 @@ class _SimpleUrlInput(_RequestDetails):
 url_input_adapter = TypeAdapter(list[_RequestsFromUrlInput | _SimpleUrlInput])
 
 
-@docs_group('Classes')
+@docs_group('Request loaders')
 class RequestList(CrawleeRequestList):
     """Extends crawlee RequestList.
 
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -5,8 +5,16 @@ const { config } = require('@apify/docs-theme');
 const { externalLinkProcessor } = require('./tools/utils/externalLink');
 
 const GROUP_ORDER = [
-    'Classes',
-    'Data structures',
+    'Actor',
+    'Charging',
+    'Configuration',
+    'Event managers',
+    'Events',
+    'Event data',
+    'Request loaders',
+    'Storage clients',
+    'Storage data',
+    'Storages',
 ];
 
 const groupSort = (g1, g2) => {
@@ -112,21 +120,132 @@ module.exports = {
                     moduleShortcutsPath: path.join(__dirname, '/module_shortcuts.json'),
                 },
                 reexports: [
+                    // Storages
+                    {
+                        url: 'https://crawlee.dev/python/api/class/Storage',
+                        group: 'Storages',
+                    },
                     {
                         url: 'https://crawlee.dev/python/api/class/Dataset',
-                        group: 'Classes',
+                        group: 'Storages',
                     },
                     {
                         url: 'https://crawlee.dev/python/api/class/KeyValueStore',
-                        group: 'Classes',
+                        group: 'Storages',
                     },
                     {
                         url: 'https://crawlee.dev/python/api/class/RequestQueue',
-                        group: 'Classes',
+                        group: 'Storages',
+                    },
+                    // Storage data
+                    {
+                        url: 'https://crawlee.dev/python/api/class/AddRequestsResponse',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/DatasetItemsListPage',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/DatasetMetadata',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/KeyValueStoreMetadata',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/KeyValueStoreRecord',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/KeyValueStoreRecordMetadata',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/ProcessedRequest',
+                        group: 'Storage data',
                     },
                     {
                         url: 'https://crawlee.dev/python/api/class/Request',
-                        group: 'Classes',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/RequestQueueMetadata',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/StorageMetadata',
+                        group: 'Storage data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/ReqUnprocessedRequestuest',
+                        group: 'Storage data',
+                    },
+                    // Event managers
+                    {
+                        url: 'https://crawlee.dev/python/api/class/EventManager',
+                        group: 'Event managers',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/LocalEventManager',
+                        group: 'Event managers',
+                    },
+                    // Events
+                    {
+                        url: 'https://crawlee.dev/python/api/enum/Event',
+                        group: 'Events',
+                    },
+                    // Event data
+                    {
+                        url: 'https://crawlee.dev/python/api/class/EventAbortingData',
+                        group: 'Event data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/EventExitData',
+                        group: 'Event data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/EventMigratingData',
+                        group: 'Event data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/EventPersistStateData',
+                        group: 'Event data',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/EventSystemInfoData',
+                        group: 'Event data',
+                    },
+                    // Storage clients
+                    {
+                        url: 'https://crawlee.dev/python/api/class/StorageClient',
+                        group: 'Storage clients',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/MemoryStorageClient',
+                        group: 'Storage clients',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/FileSystemStorageClient',
+                        group: 'Storage clients',
+                    },
+                    // Request loaders
+                    {
+                        url: 'https://crawlee.dev/python/api/class/RequestLoader',
+                        group: 'Request loaders',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/RequestManager',
+                        group: 'Request loaders',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/RequestManagerTandem',
+                        group: 'Request loaders',
+                    },
+                    {
+                        url: 'https://crawlee.dev/python/api/class/SitemapRequestLoader',
+                        group: 'Request loaders',
                     },
                 ],
             },
