docs: Improve API doc groups and polish docstrings by vdusek · Pull Request #638 · apify/apify-client-python

vdusek · 2026-02-24T09:45:56Z

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

Issues

Closes: Improve API reference documentation #637

Test plan

CI passes

🤖 Generated with Claude Code

codecov · 2026-02-24T09:47:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.71%. Comparing base (7895a4e) to head (6b8fa25).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master     #638       +/-   ##
===========================================
+ Coverage   75.60%   96.71%   +21.10%     
===========================================
  Files          45       46        +1     
  Lines        4271     4380      +109     
===========================================
+ Hits         3229     4236     +1007     
+ Misses       1042      144      -898

Flag	Coverage Δ
integration	`94.77% <100.00%> (?)`
unit	`76.21% <100.00%> (+0.60%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

vdusek · 2026-02-24T10:15:16Z

Follow-up: #642 — Add @docs_group('Models') decorators to the generated _models.py file via post-processing.

Copilot

Pull request overview

This PR refactors how the Python API reference is organized and rendered by introducing a @docs_group() decorator on public symbols and updating the docs transformation pipeline to use those group assignments, while also polishing many docstrings for consistency and clarity (as requested in #637).

Changes:

Added src/apify_client/_docs.py with a @docs_group() decorator and applied it broadly to public API symbols (clients, models, errors).
Updated website/transformDocs.js to derive documentation grouping from the Python @docs_group() decorator rather than JS-side name/kind heuristics.
Refined docstrings across the main client, HTTP clients, resource clients, and errors for more consistent “how to obtain / what it does” guidance.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`website/transformDocs.js`	Switches grouping logic to use extracted `docs_group` decorator metadata and updates group ordering.
`src/apify_client/_docs.py`	Introduces the `@docs_group()` decorator and the allowed group name literals.
`src/apify_client/_apify_client.py`	Adds `@docs_group()` to `ApifyClient`/`ApifyClientAsync` and expands/polishes their docstrings.
`src/apify_client/_http_clients/_http_client.py`	Adds `@docs_group()` to HTTP clients and improves docstrings/parameter descriptions.
`src/apify_client/errors.py`	Adds `@docs_group()` to error types and expands error docstrings.
`src/apify_client/_resource_clients/actor_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/actor.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/actor_env_var_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/actor_env_var.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/actor_version_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/actor_version.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/build_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/build.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/dataset_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/dataset.py`	Adds `@docs_group()` to clients and a model (`DatasetItemsPage`) and improves docstrings.
`src/apify_client/_resource_clients/key_value_store_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/key_value_store.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/log.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/request_queue_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/request_queue.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/run_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/run.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/schedule_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/schedule.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/status_message_watcher.py`	Adds `@docs_group()` and improves utility class docstrings.
`src/apify_client/_resource_clients/store_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/streamed_log.py`	Adds `@docs_group()` and improves utility class docstrings.
`src/apify_client/_resource_clients/task_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/task.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/user.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/webhook_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/webhook.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/webhook_dispatch_collection.py`	Adds `@docs_group()` and improves resource client docstrings.
`src/apify_client/_resource_clients/webhook_dispatch.py`	Adds `@docs_group()` and improves resource client docstrings.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

website/transformDocs.js

src/apify_client/_docs.py

src/apify_client/errors.py

Pijukatel

Looks good. I have one optional comment

src/apify_client/_resource_clients/actor.py

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>

Improve class-level docstrings for Apify API clients, resource clients, HTTP clients, and error classes to be more descriptive and consistent. Resource client docstrings now describe key operations and reference how to obtain an instance via the parent client. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Use run.default_dataset_id instead of run['defaultDatasetId'] and add None check since call() returns Run | None. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vdusek added adhoc Ad-hoc unplanned task added during the sprint. t-tooling Issues with this label are in the ownership of the tooling team. labels Feb 24, 2026

vdusek self-assigned this Feb 24, 2026

vdusek requested a review from Pijukatel February 24, 2026 09:46

github-actions bot added this to the 135th sprint - Tooling team milestone Feb 24, 2026

vdusek changed the title ~~docs: Improve API reference with docs_group decorator and polished docstrings~~ docs: Improve API doc groups and polish docstrings Feb 24, 2026

vdusek mentioned this pull request Feb 24, 2026

Add @docs_group decorator to generated models #642

Open

Pijukatel requested a review from Copilot February 25, 2026 08:15

Copilot started reviewing on behalf of Pijukatel February 25, 2026 08:16 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

website/transformDocs.js Show resolved Hide resolved

src/apify_client/_docs.py Outdated Show resolved Hide resolved

src/apify_client/errors.py Show resolved Hide resolved

Pijukatel approved these changes Feb 25, 2026

View reviewed changes

src/apify_client/_resource_clients/actor.py Outdated Show resolved Hide resolved

vdusek and others added 7 commits February 25, 2026 10:48

docs: Fix typo 'unparseable' -> 'unparsable' in docstring

ea0ce76

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: Add usage examples to ApifyClient and ApifyClientAsync docstrings

9f7f38b

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: Fix usage examples to use typed model attributes

caf52e8

Use run.default_dataset_id instead of run['defaultDatasetId'] and add None check since call() returns Run | None. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: Revert changes to generated _models.py file

6764f59

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Address comments

81b7b42

vdusek force-pushed the worktree-improve-api-docs branch from 4fc07f0 to 81b7b42 Compare February 25, 2026 09:56

vdusek merged commit 69571f0 into master Feb 25, 2026
24 checks passed

vdusek deleted the worktree-improve-api-docs branch February 25, 2026 09:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

docs: Improve API doc groups and polish docstrings#638

docs: Improve API doc groups and polish docstrings#638
vdusek merged 7 commits intomasterfrom
worktree-improve-api-docs

vdusek commented Feb 24, 2026 •

edited

Loading

Uh oh!

codecov bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

vdusek commented Feb 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Pijukatel left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

vdusek commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Screenshot

Issues

Test plan

Uh oh!

codecov bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

vdusek commented Feb 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Pijukatel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vdusek commented Feb 24, 2026 •

edited

Loading

codecov bot commented Feb 24, 2026 •

edited

Loading