From f7ab02d3cf9da975484e92324984c2692804df17 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 23 Mar 2026 03:52:07 +0000 Subject: [PATCH] Generate markdown API docs with griffe - scripts/generate_docs.py: Generate .md files from docstrings - docs/api/*.md: Auto-generated API documentation - Pre-commit hook: Auto-generate markdown on commit - Uses griffe AST parser (no code execution) Generated files: - docs/api/index.md - docs/api/kworkclient.md - docs/api/client/*.md - docs/api/models/*.md - docs/api/errors/*.md --- docs/api/client/apierrorresponse.md | 3 + docs/api/client/authresponse.md | 3 + docs/api/client/badge.md | 3 + docs/api/client/catalogresponse.md | 3 + docs/api/client/city.md | 3 + docs/api/client/country.md | 3 + docs/api/client/dataresponse.md | 3 + docs/api/client/dialog.md | 3 + docs/api/client/feature.md | 3 + docs/api/client/index.md | 33 ++++++ docs/api/client/kwork.md | 3 + docs/api/client/kworkapierror.md | 3 + docs/api/client/kworkautherror.md | 3 + docs/api/client/kworkclient.md | 36 +++++++ docs/api/client/kworkdetails.md | 3 + docs/api/client/kworkerror.md | 3 + docs/api/client/kworknetworkerror.md | 3 + docs/api/client/kworknotfounderror.md | 3 + docs/api/client/kworkratelimiterror.md | 3 + docs/api/client/kworkvalidationerror.md | 3 + docs/api/client/notificationsresponse.md | 3 + docs/api/client/project.md | 3 + docs/api/client/projectsresponse.md | 3 + docs/api/client/review.md | 3 + docs/api/client/reviewsresponse.md | 3 + docs/api/client/timezone.md | 3 + docs/api/errors/index.md | 15 +++ docs/api/errors/kworkapierror.md | 3 + docs/api/errors/kworkautherror.md | 3 + docs/api/errors/kworkerror.md | 3 + docs/api/errors/kworknetworkerror.md | 3 + docs/api/errors/kworknotfounderror.md | 3 + docs/api/errors/kworkratelimiterror.md | 3 + docs/api/errors/kworkvalidationerror.md | 3 + docs/api/index.md | 24 +++++ docs/api/kworkapierror.md | 3 + docs/api/kworkautherror.md | 3 + docs/api/kworkclient.md | 36 +++++++ docs/api/kworkerror.md | 3 + docs/api/models/apierrorresponse.md | 3 + docs/api/models/authresponse.md | 3 + docs/api/models/badge.md | 3 + docs/api/models/catalogresponse.md | 3 + docs/api/models/city.md | 3 + docs/api/models/country.md | 3 + docs/api/models/dataresponse.md | 3 + docs/api/models/dialog.md | 3 + docs/api/models/errordetail.md | 3 + docs/api/models/feature.md | 3 + docs/api/models/index.md | 30 ++++++ docs/api/models/kwork.md | 3 + docs/api/models/kworkcategory.md | 3 + docs/api/models/kworkdetails.md | 3 + docs/api/models/kworkuser.md | 3 + docs/api/models/notification.md | 3 + docs/api/models/notificationsresponse.md | 3 + docs/api/models/paginationinfo.md | 3 + docs/api/models/project.md | 3 + docs/api/models/projectsresponse.md | 3 + docs/api/models/review.md | 3 + docs/api/models/reviewsresponse.md | 3 + docs/api/models/timezone.md | 3 + scripts/generate_docs.py | 125 +++++++++++++++++++++++ 63 files changed, 467 insertions(+) create mode 100644 docs/api/client/apierrorresponse.md create mode 100644 docs/api/client/authresponse.md create mode 100644 docs/api/client/badge.md create mode 100644 docs/api/client/catalogresponse.md create mode 100644 docs/api/client/city.md create mode 100644 docs/api/client/country.md create mode 100644 docs/api/client/dataresponse.md create mode 100644 docs/api/client/dialog.md create mode 100644 docs/api/client/feature.md create mode 100644 docs/api/client/index.md create mode 100644 docs/api/client/kwork.md create mode 100644 docs/api/client/kworkapierror.md create mode 100644 docs/api/client/kworkautherror.md create mode 100644 docs/api/client/kworkclient.md create mode 100644 docs/api/client/kworkdetails.md create mode 100644 docs/api/client/kworkerror.md create mode 100644 docs/api/client/kworknetworkerror.md create mode 100644 docs/api/client/kworknotfounderror.md create mode 100644 docs/api/client/kworkratelimiterror.md create mode 100644 docs/api/client/kworkvalidationerror.md create mode 100644 docs/api/client/notificationsresponse.md create mode 100644 docs/api/client/project.md create mode 100644 docs/api/client/projectsresponse.md create mode 100644 docs/api/client/review.md create mode 100644 docs/api/client/reviewsresponse.md create mode 100644 docs/api/client/timezone.md create mode 100644 docs/api/errors/index.md create mode 100644 docs/api/errors/kworkapierror.md create mode 100644 docs/api/errors/kworkautherror.md create mode 100644 docs/api/errors/kworkerror.md create mode 100644 docs/api/errors/kworknetworkerror.md create mode 100644 docs/api/errors/kworknotfounderror.md create mode 100644 docs/api/errors/kworkratelimiterror.md create mode 100644 docs/api/errors/kworkvalidationerror.md create mode 100644 docs/api/index.md create mode 100644 docs/api/kworkapierror.md create mode 100644 docs/api/kworkautherror.md create mode 100644 docs/api/kworkclient.md create mode 100644 docs/api/kworkerror.md create mode 100644 docs/api/models/apierrorresponse.md create mode 100644 docs/api/models/authresponse.md create mode 100644 docs/api/models/badge.md create mode 100644 docs/api/models/catalogresponse.md create mode 100644 docs/api/models/city.md create mode 100644 docs/api/models/country.md create mode 100644 docs/api/models/dataresponse.md create mode 100644 docs/api/models/dialog.md create mode 100644 docs/api/models/errordetail.md create mode 100644 docs/api/models/feature.md create mode 100644 docs/api/models/index.md create mode 100644 docs/api/models/kwork.md create mode 100644 docs/api/models/kworkcategory.md create mode 100644 docs/api/models/kworkdetails.md create mode 100644 docs/api/models/kworkuser.md create mode 100644 docs/api/models/notification.md create mode 100644 docs/api/models/notificationsresponse.md create mode 100644 docs/api/models/paginationinfo.md create mode 100644 docs/api/models/project.md create mode 100644 docs/api/models/projectsresponse.md create mode 100644 docs/api/models/review.md create mode 100644 docs/api/models/reviewsresponse.md create mode 100644 docs/api/models/timezone.md create mode 100644 scripts/generate_docs.py diff --git a/docs/api/client/apierrorresponse.md b/docs/api/client/apierrorresponse.md new file mode 100644 index 0000000..b6793e2 --- /dev/null +++ b/docs/api/client/apierrorresponse.md @@ -0,0 +1,3 @@ +# APIErrorResponse + +Standard API error response. diff --git a/docs/api/client/authresponse.md b/docs/api/client/authresponse.md new file mode 100644 index 0000000..4fbdf9b --- /dev/null +++ b/docs/api/client/authresponse.md @@ -0,0 +1,3 @@ +# AuthResponse + +Authentication response. diff --git a/docs/api/client/badge.md b/docs/api/client/badge.md new file mode 100644 index 0000000..39ebed8 --- /dev/null +++ b/docs/api/client/badge.md @@ -0,0 +1,3 @@ +# Badge + +User badge information. diff --git a/docs/api/client/catalogresponse.md b/docs/api/client/catalogresponse.md new file mode 100644 index 0000000..383bce6 --- /dev/null +++ b/docs/api/client/catalogresponse.md @@ -0,0 +1,3 @@ +# CatalogResponse + +Catalog response with kworks and pagination. diff --git a/docs/api/client/city.md b/docs/api/client/city.md new file mode 100644 index 0000000..e5a044c --- /dev/null +++ b/docs/api/client/city.md @@ -0,0 +1,3 @@ +# City + +City information. diff --git a/docs/api/client/country.md b/docs/api/client/country.md new file mode 100644 index 0000000..dfcd9bc --- /dev/null +++ b/docs/api/client/country.md @@ -0,0 +1,3 @@ +# Country + +Country information. diff --git a/docs/api/client/dataresponse.md b/docs/api/client/dataresponse.md new file mode 100644 index 0000000..6b3f844 --- /dev/null +++ b/docs/api/client/dataresponse.md @@ -0,0 +1,3 @@ +# DataResponse + +Generic data response wrapper. diff --git a/docs/api/client/dialog.md b/docs/api/client/dialog.md new file mode 100644 index 0000000..ec6df2b --- /dev/null +++ b/docs/api/client/dialog.md @@ -0,0 +1,3 @@ +# Dialog + +Dialog (chat) information. diff --git a/docs/api/client/feature.md b/docs/api/client/feature.md new file mode 100644 index 0000000..2a3e800 --- /dev/null +++ b/docs/api/client/feature.md @@ -0,0 +1,3 @@ +# Feature + +Feature/addon information. diff --git a/docs/api/client/index.md b/docs/api/client/index.md new file mode 100644 index 0000000..22a9d2a --- /dev/null +++ b/docs/api/client/index.md @@ -0,0 +1,33 @@ +# client + +Kwork API Client. + +Main client class with authentication and all API endpoints. + +## Classes + +- [KworkApiError](kworkapierror.md) +- [KworkAuthError](kworkautherror.md) +- [KworkError](kworkerror.md) +- [KworkNetworkError](kworknetworkerror.md) +- [KworkNotFoundError](kworknotfounderror.md) +- [KworkRateLimitError](kworkratelimiterror.md) +- [KworkValidationError](kworkvalidationerror.md) +- [APIErrorResponse](apierrorresponse.md) +- [AuthResponse](authresponse.md) +- [Badge](badge.md) +- [CatalogResponse](catalogresponse.md) +- [City](city.md) +- [Country](country.md) +- [DataResponse](dataresponse.md) +- [Dialog](dialog.md) +- [Feature](feature.md) +- [Kwork](kwork.md) +- [KworkDetails](kworkdetails.md) +- [NotificationsResponse](notificationsresponse.md) +- [Project](project.md) +- [ProjectsResponse](projectsresponse.md) +- [Review](review.md) +- [ReviewsResponse](reviewsresponse.md) +- [TimeZone](timezone.md) +- [KworkClient](kworkclient.md) diff --git a/docs/api/client/kwork.md b/docs/api/client/kwork.md new file mode 100644 index 0000000..f17d3dd --- /dev/null +++ b/docs/api/client/kwork.md @@ -0,0 +1,3 @@ +# Kwork + +Kwork (service) information. diff --git a/docs/api/client/kworkapierror.md b/docs/api/client/kworkapierror.md new file mode 100644 index 0000000..8613c6f --- /dev/null +++ b/docs/api/client/kworkapierror.md @@ -0,0 +1,3 @@ +# KworkApiError + +API request error (4xx, 5xx). diff --git a/docs/api/client/kworkautherror.md b/docs/api/client/kworkautherror.md new file mode 100644 index 0000000..57e4bb0 --- /dev/null +++ b/docs/api/client/kworkautherror.md @@ -0,0 +1,3 @@ +# KworkAuthError + +Authentication/authorization error. diff --git a/docs/api/client/kworkclient.md b/docs/api/client/kworkclient.md new file mode 100644 index 0000000..a935655 --- /dev/null +++ b/docs/api/client/kworkclient.md @@ -0,0 +1,36 @@ +# KworkClient + +Kwork.ru API client. + +Usage: + # Login with credentials + client = await KworkClient.login("username", "password") + + # Or restore from token + client = KworkClient(token="your_web_auth_token") + + # Make requests + catalog = await client.catalog.get_list(page=1) + +## Methods + +### `login(username: str, password: str, timeout: float = 30.0)` + +Login with username and password. + +Args: + username: Kwork username or email + password: Kwork password + timeout: Request timeout + +Returns: + Authenticated KworkClient instance + +Raises: + KworkAuthError: If login fails + + +### `close()` + +Close HTTP client. + diff --git a/docs/api/client/kworkdetails.md b/docs/api/client/kworkdetails.md new file mode 100644 index 0000000..4ffbcd9 --- /dev/null +++ b/docs/api/client/kworkdetails.md @@ -0,0 +1,3 @@ +# KworkDetails + +Extended kwork details. diff --git a/docs/api/client/kworkerror.md b/docs/api/client/kworkerror.md new file mode 100644 index 0000000..2dc1019 --- /dev/null +++ b/docs/api/client/kworkerror.md @@ -0,0 +1,3 @@ +# KworkError + +Base exception for all Kwork API errors. diff --git a/docs/api/client/kworknetworkerror.md b/docs/api/client/kworknetworkerror.md new file mode 100644 index 0000000..e31a5ca --- /dev/null +++ b/docs/api/client/kworknetworkerror.md @@ -0,0 +1,3 @@ +# KworkNetworkError + +Network/connection error. diff --git a/docs/api/client/kworknotfounderror.md b/docs/api/client/kworknotfounderror.md new file mode 100644 index 0000000..7573ae6 --- /dev/null +++ b/docs/api/client/kworknotfounderror.md @@ -0,0 +1,3 @@ +# KworkNotFoundError + +Resource not found (404). diff --git a/docs/api/client/kworkratelimiterror.md b/docs/api/client/kworkratelimiterror.md new file mode 100644 index 0000000..f31f9da --- /dev/null +++ b/docs/api/client/kworkratelimiterror.md @@ -0,0 +1,3 @@ +# KworkRateLimitError + +Rate limit exceeded (429). diff --git a/docs/api/client/kworkvalidationerror.md b/docs/api/client/kworkvalidationerror.md new file mode 100644 index 0000000..df80479 --- /dev/null +++ b/docs/api/client/kworkvalidationerror.md @@ -0,0 +1,3 @@ +# KworkValidationError + +Validation error (400). diff --git a/docs/api/client/notificationsresponse.md b/docs/api/client/notificationsresponse.md new file mode 100644 index 0000000..88276cd --- /dev/null +++ b/docs/api/client/notificationsresponse.md @@ -0,0 +1,3 @@ +# NotificationsResponse + +Notifications list response. diff --git a/docs/api/client/project.md b/docs/api/client/project.md new file mode 100644 index 0000000..11db98c --- /dev/null +++ b/docs/api/client/project.md @@ -0,0 +1,3 @@ +# Project + +Project (freelance order) information. diff --git a/docs/api/client/projectsresponse.md b/docs/api/client/projectsresponse.md new file mode 100644 index 0000000..d21a450 --- /dev/null +++ b/docs/api/client/projectsresponse.md @@ -0,0 +1,3 @@ +# ProjectsResponse + +Projects list response. diff --git a/docs/api/client/review.md b/docs/api/client/review.md new file mode 100644 index 0000000..6efd379 --- /dev/null +++ b/docs/api/client/review.md @@ -0,0 +1,3 @@ +# Review + +Review information. diff --git a/docs/api/client/reviewsresponse.md b/docs/api/client/reviewsresponse.md new file mode 100644 index 0000000..dd27b1f --- /dev/null +++ b/docs/api/client/reviewsresponse.md @@ -0,0 +1,3 @@ +# ReviewsResponse + +Reviews list response. diff --git a/docs/api/client/timezone.md b/docs/api/client/timezone.md new file mode 100644 index 0000000..db82888 --- /dev/null +++ b/docs/api/client/timezone.md @@ -0,0 +1,3 @@ +# TimeZone + +Timezone information. diff --git a/docs/api/errors/index.md b/docs/api/errors/index.md new file mode 100644 index 0000000..576fe92 --- /dev/null +++ b/docs/api/errors/index.md @@ -0,0 +1,15 @@ +# errors + +Kwork API exceptions. + +All exceptions provide clear error messages for debugging. + +## Classes + +- [KworkError](kworkerror.md) +- [KworkAuthError](kworkautherror.md) +- [KworkApiError](kworkapierror.md) +- [KworkNotFoundError](kworknotfounderror.md) +- [KworkRateLimitError](kworkratelimiterror.md) +- [KworkValidationError](kworkvalidationerror.md) +- [KworkNetworkError](kworknetworkerror.md) diff --git a/docs/api/errors/kworkapierror.md b/docs/api/errors/kworkapierror.md new file mode 100644 index 0000000..8613c6f --- /dev/null +++ b/docs/api/errors/kworkapierror.md @@ -0,0 +1,3 @@ +# KworkApiError + +API request error (4xx, 5xx). diff --git a/docs/api/errors/kworkautherror.md b/docs/api/errors/kworkautherror.md new file mode 100644 index 0000000..57e4bb0 --- /dev/null +++ b/docs/api/errors/kworkautherror.md @@ -0,0 +1,3 @@ +# KworkAuthError + +Authentication/authorization error. diff --git a/docs/api/errors/kworkerror.md b/docs/api/errors/kworkerror.md new file mode 100644 index 0000000..2dc1019 --- /dev/null +++ b/docs/api/errors/kworkerror.md @@ -0,0 +1,3 @@ +# KworkError + +Base exception for all Kwork API errors. diff --git a/docs/api/errors/kworknetworkerror.md b/docs/api/errors/kworknetworkerror.md new file mode 100644 index 0000000..e31a5ca --- /dev/null +++ b/docs/api/errors/kworknetworkerror.md @@ -0,0 +1,3 @@ +# KworkNetworkError + +Network/connection error. diff --git a/docs/api/errors/kworknotfounderror.md b/docs/api/errors/kworknotfounderror.md new file mode 100644 index 0000000..7573ae6 --- /dev/null +++ b/docs/api/errors/kworknotfounderror.md @@ -0,0 +1,3 @@ +# KworkNotFoundError + +Resource not found (404). diff --git a/docs/api/errors/kworkratelimiterror.md b/docs/api/errors/kworkratelimiterror.md new file mode 100644 index 0000000..f31f9da --- /dev/null +++ b/docs/api/errors/kworkratelimiterror.md @@ -0,0 +1,3 @@ +# KworkRateLimitError + +Rate limit exceeded (429). diff --git a/docs/api/errors/kworkvalidationerror.md b/docs/api/errors/kworkvalidationerror.md new file mode 100644 index 0000000..df80479 --- /dev/null +++ b/docs/api/errors/kworkvalidationerror.md @@ -0,0 +1,3 @@ +# KworkValidationError + +Validation error (400). diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..e30f7f7 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,24 @@ +# kwork_api + +Kwork.ru API Client + +Unofficial Python client for Kwork.ru API. + +Example: + from kwork_api import KworkClient + + # Login with credentials + client = await KworkClient.login("username", "password") + + # Or restore from token + client = KworkClient(token="your_web_auth_token") + + # Get catalog + catalog = await client.catalog.get_list(page=1) + +## Classes + +- [KworkClient](kworkclient.md) +- [KworkError](kworkerror.md) +- [KworkAuthError](kworkautherror.md) +- [KworkApiError](kworkapierror.md) diff --git a/docs/api/kworkapierror.md b/docs/api/kworkapierror.md new file mode 100644 index 0000000..8613c6f --- /dev/null +++ b/docs/api/kworkapierror.md @@ -0,0 +1,3 @@ +# KworkApiError + +API request error (4xx, 5xx). diff --git a/docs/api/kworkautherror.md b/docs/api/kworkautherror.md new file mode 100644 index 0000000..57e4bb0 --- /dev/null +++ b/docs/api/kworkautherror.md @@ -0,0 +1,3 @@ +# KworkAuthError + +Authentication/authorization error. diff --git a/docs/api/kworkclient.md b/docs/api/kworkclient.md new file mode 100644 index 0000000..a935655 --- /dev/null +++ b/docs/api/kworkclient.md @@ -0,0 +1,36 @@ +# KworkClient + +Kwork.ru API client. + +Usage: + # Login with credentials + client = await KworkClient.login("username", "password") + + # Or restore from token + client = KworkClient(token="your_web_auth_token") + + # Make requests + catalog = await client.catalog.get_list(page=1) + +## Methods + +### `login(username: str, password: str, timeout: float = 30.0)` + +Login with username and password. + +Args: + username: Kwork username or email + password: Kwork password + timeout: Request timeout + +Returns: + Authenticated KworkClient instance + +Raises: + KworkAuthError: If login fails + + +### `close()` + +Close HTTP client. + diff --git a/docs/api/kworkerror.md b/docs/api/kworkerror.md new file mode 100644 index 0000000..2dc1019 --- /dev/null +++ b/docs/api/kworkerror.md @@ -0,0 +1,3 @@ +# KworkError + +Base exception for all Kwork API errors. diff --git a/docs/api/models/apierrorresponse.md b/docs/api/models/apierrorresponse.md new file mode 100644 index 0000000..b6793e2 --- /dev/null +++ b/docs/api/models/apierrorresponse.md @@ -0,0 +1,3 @@ +# APIErrorResponse + +Standard API error response. diff --git a/docs/api/models/authresponse.md b/docs/api/models/authresponse.md new file mode 100644 index 0000000..4fbdf9b --- /dev/null +++ b/docs/api/models/authresponse.md @@ -0,0 +1,3 @@ +# AuthResponse + +Authentication response. diff --git a/docs/api/models/badge.md b/docs/api/models/badge.md new file mode 100644 index 0000000..39ebed8 --- /dev/null +++ b/docs/api/models/badge.md @@ -0,0 +1,3 @@ +# Badge + +User badge information. diff --git a/docs/api/models/catalogresponse.md b/docs/api/models/catalogresponse.md new file mode 100644 index 0000000..383bce6 --- /dev/null +++ b/docs/api/models/catalogresponse.md @@ -0,0 +1,3 @@ +# CatalogResponse + +Catalog response with kworks and pagination. diff --git a/docs/api/models/city.md b/docs/api/models/city.md new file mode 100644 index 0000000..e5a044c --- /dev/null +++ b/docs/api/models/city.md @@ -0,0 +1,3 @@ +# City + +City information. diff --git a/docs/api/models/country.md b/docs/api/models/country.md new file mode 100644 index 0000000..dfcd9bc --- /dev/null +++ b/docs/api/models/country.md @@ -0,0 +1,3 @@ +# Country + +Country information. diff --git a/docs/api/models/dataresponse.md b/docs/api/models/dataresponse.md new file mode 100644 index 0000000..6b3f844 --- /dev/null +++ b/docs/api/models/dataresponse.md @@ -0,0 +1,3 @@ +# DataResponse + +Generic data response wrapper. diff --git a/docs/api/models/dialog.md b/docs/api/models/dialog.md new file mode 100644 index 0000000..ec6df2b --- /dev/null +++ b/docs/api/models/dialog.md @@ -0,0 +1,3 @@ +# Dialog + +Dialog (chat) information. diff --git a/docs/api/models/errordetail.md b/docs/api/models/errordetail.md new file mode 100644 index 0000000..068cd3c --- /dev/null +++ b/docs/api/models/errordetail.md @@ -0,0 +1,3 @@ +# ErrorDetail + +Error detail from API. diff --git a/docs/api/models/feature.md b/docs/api/models/feature.md new file mode 100644 index 0000000..2a3e800 --- /dev/null +++ b/docs/api/models/feature.md @@ -0,0 +1,3 @@ +# Feature + +Feature/addon information. diff --git a/docs/api/models/index.md b/docs/api/models/index.md new file mode 100644 index 0000000..e8acd01 --- /dev/null +++ b/docs/api/models/index.md @@ -0,0 +1,30 @@ +# models + +Pydantic models for Kwork API responses. + +All models follow the structure found in the HAR dump analysis. + +## Classes + +- [KworkUser](kworkuser.md) +- [KworkCategory](kworkcategory.md) +- [Kwork](kwork.md) +- [KworkDetails](kworkdetails.md) +- [PaginationInfo](paginationinfo.md) +- [CatalogResponse](catalogresponse.md) +- [Project](project.md) +- [ProjectsResponse](projectsresponse.md) +- [Review](review.md) +- [ReviewsResponse](reviewsresponse.md) +- [Notification](notification.md) +- [NotificationsResponse](notificationsresponse.md) +- [Dialog](dialog.md) +- [AuthResponse](authresponse.md) +- [ErrorDetail](errordetail.md) +- [APIErrorResponse](apierrorresponse.md) +- [City](city.md) +- [Country](country.md) +- [TimeZone](timezone.md) +- [Feature](feature.md) +- [Badge](badge.md) +- [DataResponse](dataresponse.md) diff --git a/docs/api/models/kwork.md b/docs/api/models/kwork.md new file mode 100644 index 0000000..f17d3dd --- /dev/null +++ b/docs/api/models/kwork.md @@ -0,0 +1,3 @@ +# Kwork + +Kwork (service) information. diff --git a/docs/api/models/kworkcategory.md b/docs/api/models/kworkcategory.md new file mode 100644 index 0000000..4c1ab81 --- /dev/null +++ b/docs/api/models/kworkcategory.md @@ -0,0 +1,3 @@ +# KworkCategory + +Category information. diff --git a/docs/api/models/kworkdetails.md b/docs/api/models/kworkdetails.md new file mode 100644 index 0000000..4ffbcd9 --- /dev/null +++ b/docs/api/models/kworkdetails.md @@ -0,0 +1,3 @@ +# KworkDetails + +Extended kwork details. diff --git a/docs/api/models/kworkuser.md b/docs/api/models/kworkuser.md new file mode 100644 index 0000000..0627ce6 --- /dev/null +++ b/docs/api/models/kworkuser.md @@ -0,0 +1,3 @@ +# KworkUser + +User information. diff --git a/docs/api/models/notification.md b/docs/api/models/notification.md new file mode 100644 index 0000000..1da4bb9 --- /dev/null +++ b/docs/api/models/notification.md @@ -0,0 +1,3 @@ +# Notification + +Notification information. diff --git a/docs/api/models/notificationsresponse.md b/docs/api/models/notificationsresponse.md new file mode 100644 index 0000000..88276cd --- /dev/null +++ b/docs/api/models/notificationsresponse.md @@ -0,0 +1,3 @@ +# NotificationsResponse + +Notifications list response. diff --git a/docs/api/models/paginationinfo.md b/docs/api/models/paginationinfo.md new file mode 100644 index 0000000..1f73ca8 --- /dev/null +++ b/docs/api/models/paginationinfo.md @@ -0,0 +1,3 @@ +# PaginationInfo + +Pagination metadata. diff --git a/docs/api/models/project.md b/docs/api/models/project.md new file mode 100644 index 0000000..11db98c --- /dev/null +++ b/docs/api/models/project.md @@ -0,0 +1,3 @@ +# Project + +Project (freelance order) information. diff --git a/docs/api/models/projectsresponse.md b/docs/api/models/projectsresponse.md new file mode 100644 index 0000000..d21a450 --- /dev/null +++ b/docs/api/models/projectsresponse.md @@ -0,0 +1,3 @@ +# ProjectsResponse + +Projects list response. diff --git a/docs/api/models/review.md b/docs/api/models/review.md new file mode 100644 index 0000000..6efd379 --- /dev/null +++ b/docs/api/models/review.md @@ -0,0 +1,3 @@ +# Review + +Review information. diff --git a/docs/api/models/reviewsresponse.md b/docs/api/models/reviewsresponse.md new file mode 100644 index 0000000..dd27b1f --- /dev/null +++ b/docs/api/models/reviewsresponse.md @@ -0,0 +1,3 @@ +# ReviewsResponse + +Reviews list response. diff --git a/docs/api/models/timezone.md b/docs/api/models/timezone.md new file mode 100644 index 0000000..db82888 --- /dev/null +++ b/docs/api/models/timezone.md @@ -0,0 +1,3 @@ +# TimeZone + +Timezone information. diff --git a/scripts/generate_docs.py b/scripts/generate_docs.py new file mode 100644 index 0000000..d7e6377 --- /dev/null +++ b/scripts/generate_docs.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +""" +Generate Markdown API documentation using griffe. + +Usage: + python scripts/generate_docs.py + +Generates docs/api/*.md from source code docstrings. +""" + +import sys +from pathlib import Path + +from griffe import GriffeLoader, ObjectKind + + +def format_signature(obj): + """Format object signature.""" + params = [] + for param in obj.parameters: + if param.name in ("self", "cls"): + continue + p = param.name + if param.annotation: + p += f": {param.annotation}" + if param.default: + p += f" = {param.default}" + params.append(p) + return f"({', '.join(params)})" + + +def generate_class_md(cls, output_path: Path): + """Generate markdown for a class.""" + lines = [ + f"# {cls.name}", + "", + cls.docstring.value if cls.docstring else "", + "", + ] + + # Methods + methods = [m for m in cls.members.values() if m.kind == ObjectKind.FUNCTION and not m.name.startswith("_")] + + if methods: + lines.append("## Methods") + lines.append("") + + for method in methods: + sig = format_signature(method) + lines.append(f"### `{method.name}{sig}`") + lines.append("") + + if method.docstring: + lines.append(method.docstring.value) + lines.append("") + + lines.append("") + + output_path.write_text("\n".join(lines)) + + +def generate_module_md(module, output_dir: Path): + """Generate markdown files for a module.""" + output_dir.mkdir(parents=True, exist_ok=True) + + # Generate index for module + index_path = output_dir / "index.md" + lines = [ + f"# {module.name}", + "", + module.docstring.value if module.docstring else "", + "", + "## Classes", + "", + ] + + for name, obj in module.members.items(): + if obj.kind == ObjectKind.CLASS and not name.startswith("_"): + lines.append(f"- [{name}]({name.lower()}.md)") + # Generate class file + class_path = output_dir / f"{name.lower()}.md" + generate_class_md(obj, class_path) + + lines.append("") + index_path.write_text("\n".join(lines)) + + +def main(): + """Main entry point.""" + root_dir = Path(__file__).parent.parent + src_dir = root_dir / "src" / "kwork_api" + docs_dir = root_dir / "docs" / "api" + + if not src_dir.exists(): + print(f"❌ Source directory not found: {src_dir}") + sys.exit(1) + + print("📝 Loading source code with griffe...") + + # Load with griffe (AST parsing, no code execution) + loader = GriffeLoader(search_paths=[src_dir.parent]) + module = loader.load("kwork_api") + + print("📄 Generating markdown documentation...") + + # Generate for main modules + generate_module_md(module, docs_dir) + + # Generate client.md + if "client" in module.members: + generate_module_md(module["client"], docs_dir / "client") + + # Generate models.md + if "models" in module.members: + generate_module_md(module["models"], docs_dir / "models") + + # Generate errors.md + if "errors" in module.members: + generate_module_md(module["errors"], docs_dir / "errors") + + print(f"✅ Generated markdown in {docs_dir}") + + +if __name__ == "__main__": + main()