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

@@ -0,0 +1,3 @@
+# APIErrorResponse
+
+Standard API error response.

docs/api/client/authresponse.md

@@ -0,0 +1,3 @@
+# AuthResponse
+
+Authentication response.

docs/api/client/badge.md

@@ -0,0 +1,3 @@
+# Badge
+
+User badge information.

docs/api/client/catalogresponse.md

@@ -0,0 +1,3 @@
+# CatalogResponse
+
+Catalog response with kworks and pagination.

docs/api/client/city.md

@@ -0,0 +1,3 @@
+# City
+
+City information.

docs/api/client/country.md

@@ -0,0 +1,3 @@
+# Country
+
+Country information.

docs/api/client/dataresponse.md

@@ -0,0 +1,3 @@
+# DataResponse
+
+Generic data response wrapper.

docs/api/client/dialog.md

@@ -0,0 +1,3 @@
+# Dialog
+
+Dialog (chat) information.

docs/api/client/feature.md

@@ -0,0 +1,3 @@
+# Feature
+
+Feature/addon information.

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)

docs/api/client/kwork.md

@@ -0,0 +1,3 @@
+# Kwork
+
+Kwork (service) information.

docs/api/client/kworkapierror.md

@@ -0,0 +1,3 @@
+# KworkApiError
+
+API request error (4xx, 5xx).

docs/api/client/kworkautherror.md

@@ -0,0 +1,3 @@
+# KworkAuthError
+
+Authentication/authorization error.

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.
+

docs/api/client/kworkdetails.md

@@ -0,0 +1,3 @@
+# KworkDetails
+
+Extended kwork details.

docs/api/client/kworkerror.md

@@ -0,0 +1,3 @@
+# KworkError
+
+Base exception for all Kwork API errors.

docs/api/client/kworknetworkerror.md

@@ -0,0 +1,3 @@
+# KworkNetworkError
+
+Network/connection error.

docs/api/client/kworknotfounderror.md

@@ -0,0 +1,3 @@
+# KworkNotFoundError
+
+Resource not found (404).

docs/api/client/kworkratelimiterror.md

@@ -0,0 +1,3 @@
+# KworkRateLimitError
+
+Rate limit exceeded (429).

docs/api/client/kworkvalidationerror.md

@@ -0,0 +1,3 @@
+# KworkValidationError
+
+Validation error (400).

docs/api/client/notificationsresponse.md

@@ -0,0 +1,3 @@
+# NotificationsResponse
+
+Notifications list response.

docs/api/client/project.md

@@ -0,0 +1,3 @@
+# Project
+
+Project (freelance order) information.

docs/api/client/projectsresponse.md

@@ -0,0 +1,3 @@
+# ProjectsResponse
+
+Projects list response.

docs/api/client/review.md

@@ -0,0 +1,3 @@
+# Review
+
+Review information.

docs/api/client/reviewsresponse.md

@@ -0,0 +1,3 @@
+# ReviewsResponse
+
+Reviews list response.

docs/api/client/timezone.md

@@ -0,0 +1,3 @@
+# TimeZone
+
+Timezone information.

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)

docs/api/errors/kworkapierror.md

@@ -0,0 +1,3 @@
+# KworkApiError
+
+API request error (4xx, 5xx).

docs/api/errors/kworkautherror.md

@@ -0,0 +1,3 @@
+# KworkAuthError
+
+Authentication/authorization error.

docs/api/errors/kworkerror.md

@@ -0,0 +1,3 @@
+# KworkError
+
+Base exception for all Kwork API errors.

docs/api/errors/kworknetworkerror.md

@@ -0,0 +1,3 @@
+# KworkNetworkError
+
+Network/connection error.

docs/api/errors/kworknotfounderror.md

@@ -0,0 +1,3 @@
+# KworkNotFoundError
+
+Resource not found (404).

docs/api/errors/kworkratelimiterror.md

@@ -0,0 +1,3 @@
+# KworkRateLimitError
+
+Rate limit exceeded (429).

docs/api/errors/kworkvalidationerror.md

@@ -0,0 +1,3 @@
+# KworkValidationError
+
+Validation error (400).

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)

docs/api/kworkapierror.md

@@ -0,0 +1,3 @@
+# KworkApiError
+
+API request error (4xx, 5xx).

docs/api/kworkautherror.md

@@ -0,0 +1,3 @@
+# KworkAuthError
+
+Authentication/authorization error.

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.
+

docs/api/kworkerror.md

@@ -0,0 +1,3 @@
+# KworkError
+
+Base exception for all Kwork API errors.

docs/api/models/apierrorresponse.md

@@ -0,0 +1,3 @@
+# APIErrorResponse
+
+Standard API error response.

docs/api/models/authresponse.md

@@ -0,0 +1,3 @@
+# AuthResponse
+
+Authentication response.

docs/api/models/badge.md

@@ -0,0 +1,3 @@
+# Badge
+
+User badge information.

docs/api/models/catalogresponse.md

@@ -0,0 +1,3 @@
+# CatalogResponse
+
+Catalog response with kworks and pagination.

docs/api/models/city.md

@@ -0,0 +1,3 @@
+# City
+
+City information.

docs/api/models/country.md

@@ -0,0 +1,3 @@
+# Country
+
+Country information.

docs/api/models/dataresponse.md

@@ -0,0 +1,3 @@
+# DataResponse
+
+Generic data response wrapper.

docs/api/models/dialog.md

@@ -0,0 +1,3 @@
+# Dialog
+
+Dialog (chat) information.

docs/api/models/errordetail.md

@@ -0,0 +1,3 @@
+# ErrorDetail
+
+Error detail from API.

docs/api/models/feature.md

@@ -0,0 +1,3 @@
+# Feature
+
+Feature/addon information.

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)

docs/api/models/kwork.md

@@ -0,0 +1,3 @@
+# Kwork
+
+Kwork (service) information.

docs/api/models/kworkcategory.md

@@ -0,0 +1,3 @@
+# KworkCategory
+
+Category information.

docs/api/models/kworkdetails.md

@@ -0,0 +1,3 @@
+# KworkDetails
+
+Extended kwork details.

docs/api/models/kworkuser.md

@@ -0,0 +1,3 @@
+# KworkUser
+
+User information.

docs/api/models/notification.md

@@ -0,0 +1,3 @@
+# Notification
+
+Notification information.

docs/api/models/notificationsresponse.md

@@ -0,0 +1,3 @@
+# NotificationsResponse
+
+Notifications list response.

docs/api/models/paginationinfo.md

@@ -0,0 +1,3 @@
+# PaginationInfo
+
+Pagination metadata.

docs/api/models/project.md

@@ -0,0 +1,3 @@
+# Project
+
+Project (freelance order) information.

docs/api/models/projectsresponse.md

@@ -0,0 +1,3 @@
+# ProjectsResponse
+
+Projects list response.

docs/api/models/review.md

@@ -0,0 +1,3 @@
+# Review
+
+Review information.

docs/api/models/reviewsresponse.md

@@ -0,0 +1,3 @@
+# ReviewsResponse
+
+Reviews list response.

docs/api/models/timezone.md

@@ -0,0 +1,3 @@
+# TimeZone
+
+Timezone information.

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()