ci: Improve model regeneration workflow

.github/workflows/manual_regenerate_models.yaml

@@ -17,6 +17,10 @@ on:
         description: Workflow run ID in apify/apify-docs that built the OpenAPI spec artifact (optional for manual runs)
         required: false
         type: string
+      docs_pr_author:
+        description: GitHub login of the apify-docs PR author (optional for manual runs)
+        required: false
+        type: string
 
 permissions:
   contents: write
@@ -35,6 +39,9 @@ jobs:
       DOCS_PR_NUMBER: ${{ inputs.docs_pr_number }}
       BRANCH: ${{ inputs.docs_pr_number && format('update-models-docs-pr-{0}', inputs.docs_pr_number) || 'update-models-manual' }}
       TITLE: "${{ inputs.docs_pr_number && format('[TODO]: update generated models from apify-docs PR #{0}', inputs.docs_pr_number) || '[TODO]: update generated models from published OpenAPI spec' }}"
+      ASSIGNEE: ${{ inputs.docs_pr_author || github.actor }}
+      REVIEWER: vdusek
+      LABEL: t-tooling
 
     steps:
       - name: Validate inputs
@@ -54,6 +61,17 @@ jobs:
         with:
           token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
 
+      # If the branch already exists on the remote (e.g. from a previous run, possibly with
+      # reviewer commits), check it out to build on top of it instead of starting fresh.
+      - name: Switch to existing branch or create a new one
+        run: |
+          if git ls-remote --exit-code --heads origin "$BRANCH" > /dev/null 2>&1; then
+            git fetch origin "$BRANCH"
+            git switch "$BRANCH"
+          else
+            git switch -c "$BRANCH"
+          fi
+
       # Download the pre-built OpenAPI spec artifact from the apify-docs workflow run.
       # Skipped for manual runs — datamodel-codegen will fetch from the published spec URL instead.
       - name: Download OpenAPI spec artifact
@@ -84,17 +102,16 @@ jobs:
             uv run poe generate-models
           fi
 
-      - name: Commit model changes
+      - name: Commit and push model changes
         id: commit
         uses: EndBug/add-and-commit@v10
         with:
           add: src/apify_client/_models.py
           author_name: apify-service-account
           author_email: apify-service-account@users.noreply.github.com
           message: ${{ env.TITLE }}
-          new_branch: ${{ env.BRANCH }}
           commit: --no-verify
-          push: -u origin ${{ env.BRANCH }} --force
+          push: -u origin ${{ env.BRANCH }}
 
       - name: Create or update PR
         if: steps.commit.outputs.committed == 'true'
@@ -111,34 +128,19 @@ jobs:
           else
             if [[ -n "$DOCS_PR_NUMBER" ]]; then
               DOCS_PR_URL="https://github.com/apify/apify-docs/pull/${DOCS_PR_NUMBER}"
-              BODY=$(cat <<EOF
-          This PR updates the auto-generated Pydantic models based on OpenAPI specification changes in [apify-docs PR #${DOCS_PR_NUMBER}](${DOCS_PR_URL}).
-
-          ## Changes
-
-          - Regenerated \`src/apify_client/_models.py\` using \`datamodel-codegen\`
-
-          ## Source
-
-          - apify-docs PR: ${DOCS_PR_URL}
-          EOF
-              )
+              BODY="This PR updates the auto-generated Pydantic models based on OpenAPI specification changes in [apify-docs PR #${DOCS_PR_NUMBER}](${DOCS_PR_URL})."
             else
-              BODY=$(cat <<EOF
-          This PR updates the auto-generated Pydantic models from the published OpenAPI specification.
-
-          ## Changes
-
-          - Regenerated \`src/apify_client/_models.py\` using \`datamodel-codegen\`
-          EOF
-              )
+              BODY="This PR updates the auto-generated Pydantic models from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json)."
             fi
 
             PR_URL=$(gh pr create \
               --title "$TITLE" \
               --body "$BODY" \
               --head "$BRANCH" \
-              --base master)
+              --base master \
+              --reviewer "$REVIEWER" \
+              --assignee "$ASSIGNEE" \
+              --label "$LABEL")
             echo "Created PR: $PR_URL"
             echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT"
             echo "created=true" >> "$GITHUB_OUTPUT"

scripts/postprocess_generated_models.py

@@ -8,6 +8,8 @@
   nested-$ref limitation), causing datamodel-codegen to generate a duplicate `Type(StrEnum)`
   class alongside the canonical `ErrorType(StrEnum)`. This script removes the duplicate and
   rewires references to use `ErrorType`.
+- Missing @docs_group decorator: Adds `@docs_group('Models')` to all model classes for API
+  reference documentation grouping, along with the required import.
 """
 
 from __future__ import annotations
@@ -51,10 +53,27 @@ def deduplicate_error_type_enum(content: str) -> str:
     return re.sub(r'\n{3,}', '\n\n\n', content)
 
 
+def add_docs_group_decorators(content: str) -> str:
+    """Add `@docs_group('Models')` decorator to all model classes and the required import."""
+    # Add the import after the existing imports.
+    content = re.sub(
+        r'(from pydantic import [^\n]+\n)',
+        r'\1\nfrom apify_client._docs import docs_group\n',
+        content,
+    )
+    # Add @docs_group('Models') before every class definition.
+    return re.sub(
+        r'\nclass ',
+        "\n@docs_group('Models')\nclass ",
+        content,
+    )
+
+
 def main() -> None:
     content = MODELS_PATH.read_text()
     fixed = fix_discriminators(content)
     fixed = deduplicate_error_type_enum(fixed)
+    fixed = add_docs_group_decorators(fixed)
 
     if fixed != content:
         MODELS_PATH.write_text(fixed)