docs: bump the docusaurus plugin

Author: barjin

Makefile

@@ -49,7 +49,7 @@ build-api-reference:
 	cd website && poetry run ./build_api_reference.sh
 
 build-docs:
-	cd website && npm clean-install && npm run build
+	cd website && npm clean-install && poetry run npm run build
 
 run-docs: build-api-reference
-	cd website && npm clean-install && npm run start
+	cd website && npm clean-install && poetry run npm run start

src/apify/_actor.py

@@ -22,7 +22,7 @@
 from apify._models import ActorRun
 from apify._platform_event_manager import EventManager, LocalEventManager, PlatformEventManager
 from apify._proxy_configuration import ProxyConfiguration
-from apify._utils import get_system_info, is_running_in_ipython
+from apify._utils import get_system_info, is_running_in_ipython, docs_group, docs_name
 from apify.apify_storage_client import ApifyStorageClient
 from apify.log import _configure_logging, logger
 from apify.storages import Dataset, KeyValueStore, RequestQueue
@@ -38,7 +38,8 @@
 
 MainReturnType = TypeVar('MainReturnType')
 
-
+@docs_name('Actor')
+@docs_group('Classes')
 class _ActorType:
     """The class of `Actor`. Only make a new instance if you're absolutely sure you need to."""
 

src/apify/_configuration.py

@@ -11,7 +11,9 @@
 from crawlee._utils.urls import validate_http_url
 from crawlee.configuration import Configuration as CrawleeConfiguration
 
+from apify._utils import docs_group
 
+@docs_group('Classes')
 class Configuration(CrawleeConfiguration):
     """A class for specifying the configuration of an Actor.
 

src/apify/_models.py

@@ -10,7 +10,9 @@
 from crawlee._utils.models import timedelta_ms
 from crawlee._utils.urls import validate_http_url
 
+from apify._utils import docs_group
 
+@docs_group('Data structures')
 class Webhook(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -28,13 +30,13 @@ class Webhook(BaseModel):
         Field(description='Template for the payload sent by the webook'),
     ] = None
 
-
+@docs_group('Data structures')
 class ActorRunMeta(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
     origin: Annotated[MetaOrigin, Field()]
 
-
+@docs_group('Data structures')
 class ActorRunStats(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -54,7 +56,7 @@ class ActorRunStats(BaseModel):
     metamorph: Annotated[int | None, Field(alias='metamorph')] = None
     compute_units: Annotated[float, Field(alias='computeUnits')]
 
-
+@docs_group('Data structures')
 class ActorRunOptions(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -63,7 +65,7 @@ class ActorRunOptions(BaseModel):
     memory_mbytes: Annotated[int, Field(alias='memoryMbytes')]
     disk_mbytes: Annotated[int, Field(alias='diskMbytes')]
 
-
+@docs_group('Data structures')
 class ActorRunUsage(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 
@@ -80,7 +82,7 @@ class ActorRunUsage(BaseModel):
     proxy_residential_transfer_gbytes: Annotated[float | None, Field(alias='PROXY_RESIDENTIAL_TRANSFER_GBYTES')] = None
     proxy_serps: Annotated[float | None, Field(alias='PROXY_SERPS')] = None
 
-
+@docs_group('Data structures')
 class ActorRun(BaseModel):
     __model_config__ = ConfigDict(populate_by_name=True)
 

src/apify/_platform_event_manager.py

@@ -21,6 +21,8 @@
 
 from apify.log import logger
 
+from apify._utils import docs_group
+
 if TYPE_CHECKING:
     from types import TracebackType
 
@@ -29,12 +31,12 @@
 
 __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')
 class SystemInfoEventData(BaseModel):
     mem_avg_bytes: Annotated[float, Field(alias='memAvgBytes')]
     mem_current_bytes: Annotated[float, Field(alias='memCurrentBytes')]
@@ -60,27 +62,27 @@ def to_crawlee_format(self) -> EventSystemInfoData:
             }
         )
 
-
+@docs_group('Data structures')
 class SystemInfoEvent(BaseModel):
     name: Literal[Event.SYSTEM_INFO]
     data: SystemInfoEventData
 
-
+@docs_group('Data structures')
 class MigratingEvent(BaseModel):
     name: Literal[Event.MIGRATING]
     data: Annotated[EventMigratingData, Field(default_factory=EventMigratingData)]
 
-
+@docs_group('Data structures')
 class AbortingEvent(BaseModel):
     name: Literal[Event.ABORTING]
     data: Annotated[EventAbortingData, Field(default_factory=EventAbortingData)]
 
-
+@docs_group('Data structures')
 class ExitEvent(BaseModel):
     name: Literal[Event.EXIT]
     data: Annotated[EventExitData, Field(default_factory=EventExitData)]
 
-
+@docs_group('Data structures')
 class EventWithoutData(BaseModel):
     name: Literal[
         Event.SESSION_RETIRED,
@@ -92,12 +94,12 @@ class EventWithoutData(BaseModel):
     ]
     data: Any = None
 
-
+@docs_group('Data structures')
 class DeprecatedEvent(BaseModel):
     name: Literal['cpuInfo']
     data: Annotated[dict[str, Any], Field(default_factory=dict)]
 
-
+@docs_group('Data structures')
 class UnknownEvent(BaseModel):
     name: str
     data: Annotated[dict[str, Any], Field(default_factory=dict)]
@@ -123,8 +125,7 @@ class UnknownEvent(BaseModel):
         UnknownEvent,
     ]
 )
-
-
+@docs_group('Classes')
 class PlatformEventManager(EventManager):
     """A class for managing Actor events.
 

src/apify/_proxy_configuration.py

@@ -18,6 +18,8 @@
 from apify._configuration import Configuration
 from apify.log import logger
 
+from apify._utils import docs_group
+
 if TYPE_CHECKING:
     from apify_client import ApifyClientAsync
     from crawlee import Request
@@ -68,6 +70,7 @@ def _check(
         raise ValueError(f'{error_str} does not match pattern {pattern.pattern!r}')
 
 
+@docs_group('Classes')
 @dataclass
 class ProxyInfo(CrawleeProxyInfo):
     """Provides information about a proxy connection that is used for requests."""
@@ -86,7 +89,7 @@ class ProxyInfo(CrawleeProxyInfo):
     This parameter is optional, by default, the proxy uses all available proxy servers from all countries.
     """
 
-
+@docs_group('Classes')
 class ProxyConfiguration(CrawleeProxyConfiguration):
     """Configures a connection to a proxy server with the provided options.
 

src/apify/_utils.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Callable, Literal
+
 import builtins
 import sys
 from importlib import metadata
@@ -24,3 +26,29 @@ def get_system_info() -> dict:
 
 def is_running_in_ipython() -> bool:
     return getattr(builtins, '__IPYTHON__', False)
+
+GroupName = Literal['Classes', 'Abstract classes', 'Data structures', 'Errors', 'Functions']
+
+def docs_group(group_name: GroupName) -> Callable:  # noqa: ARG001
+    """Decorator to mark symbols for rendering and grouping in documentation.
+
+    This decorator is used purely for documentation purposes and does not alter the behavior
+    of the decorated callable.
+    """
+
+    def wrapper(func: Callable) -> Callable:
+        return func
+
+    return wrapper
+
+def docs_name(symbol_name: str) -> Callable:
+    """Decorator for renaming symbols in documentation. This changes the rendered name of the symbol only in the web documentation.
+
+    This decorator is used purely for documentation purposes and does not alter the behavior
+    of the decorated callable.
+    """
+
+    def wrapper(func: Callable) -> Callable:
+        return func
+
+    return wrapper

src/apify/apify_storage_client/_apify_storage_client.py

@@ -12,7 +12,9 @@
 from apify.apify_storage_client._request_queue_client import RequestQueueClient
 from apify.apify_storage_client._request_queue_collection_client import RequestQueueCollectionClient
 
+from apify._utils import docs_group
 
+@docs_group('Classes')
 class ApifyStorageClient(BaseStorageClient):
     """A storage client implementation based on the Apify platform storage."""
 

website/build_api_reference.sh

@@ -1,39 +1,4 @@
 #!/bin/bash
 
-# On macOS, sed requires a space between -i and '' to specify no backup should be done
-# On Linux, sed requires no space between -i and '' to specify no backup should be done
-sed_no_backup() {
-    if [[ $(uname) = "Darwin" ]]; then
-        sed -i '' "$@"
-    else
-        sed -i'' "$@"
-    fi
-}
-
-# Create docspec dump of this package's source code through pydoc-markdown
-python ./pydoc-markdown/generate_ast.py > docspec-dump.jsonl
-sed_no_backup "s#${PWD}/..#REPO_ROOT_PLACEHOLDER#g" docspec-dump.jsonl
-
-# Create docpec dump from the right version of the apify-shared package
-apify_shared_version=$(python -c "import apify_shared; print(apify_shared.__version__)")
-apify_shared_tempdir=$(realpath "$(mktemp -d)")
-git clone --quiet https://github.com/apify/apify-shared-python.git "${apify_shared_tempdir}"
-cp ./pydoc-markdown.yml "${apify_shared_tempdir}/pydoc-markdown.yml"
-sed_no_backup "s#search_path: \[../src\]#search_path: \[./src\]#g" "${apify_shared_tempdir}/pydoc-markdown.yml"
-
-(
-    cd "${apify_shared_tempdir}";
-    git checkout --quiet "v${apify_shared_version}";
-    pydoc-markdown --quiet --dump > ./apify-shared-docspec-dump.jsonl
-)
-
-cp "${apify_shared_tempdir}/apify-shared-docspec-dump.jsonl" .
-sed_no_backup "s#${apify_shared_tempdir}#REPO_ROOT_PLACEHOLDER#g" apify-shared-docspec-dump.jsonl
-
-rm -rf "${apify_shared_tempdir}"
-
 # Generate import shortcuts from the modules
 python generate_module_shortcuts.py
-
-# Transform the docpec dumps into Typedoc-compatible docs tree
-node transformDocs.js

website/docusaurus.config.js

@@ -1,7 +1,20 @@
-/* eslint-disable global-require,import/no-extraneous-dependencies */
+const path = require('path');
+
 const { config } = require('@apify/docs-theme');
+
 const { externalLinkProcessor } = require('./tools/utils/externalLink');
-const { groupSort } = require('./transformDocs.js');
+
+const GROUP_ORDER = [
+    'Classes',
+    'Data structures',
+];
+
+const groupSort = (g1, g2) => {
+    if (GROUP_ORDER.includes(g1) && GROUP_ORDER.includes(g2)) {
+        return GROUP_ORDER.indexOf(g1) - GROUP_ORDER.indexOf(g2);
+    }
+    return g1.localeCompare(g2);
+};
 
 const { absoluteUrl } = config;
 
@@ -83,10 +96,18 @@ module.exports = {
                 typedocOptions: {
                     excludeExternals: false,
                 },
-                pathToCurrentVersionTypedocJSON: `${__dirname}/api-typedoc-generated.json`,
                 sortSidebar: groupSort,
                 routeBasePath: 'reference',
                 python: true,
+                pythonOptions: {
+                    pythonModulePath: path.join(__dirname, '../src/apify'),
+                    moduleShortcutsPath: path.join(__dirname, '/module_shortcuts.json'),
+                },
+                // reexports: [
+                //     {
+                //         url: 'http://localhost:3000/python/api/class/Dataset',
+                //     },
+                // ],
             },
         ],
         ...config.plugins,