[build] fix documentation generation tasks

commits should happen in the workflow not in the rake task

Author: titusfortner

.github/workflows/update-documentation.yml

@@ -3,227 +3,87 @@ name: Update Documentation
 on:
   workflow_dispatch:
     inputs:
-      tag:
-        description: Release tag (e.g. selenium-4.21.0)
+      version:
+        description: Release version (e.g., 4.21.0)
         required: true
         type: string
+      language:
+        description: language documentation
+        required: true
+        type: choice
+        default: "all"
+        options:
+          - java
+          - rb
+          - py
+          - dotnet
+          - node
+          - all
 
   workflow_call:
     inputs:
-      tag:
+      version:
+        required: true
+        type: string
+      sha:
         required: true
         type: string
+    language:
+      required: false
+      type: string
+      default: "all"
 
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
 jobs:
-  determine-language:
-    runs-on: ubuntu-latest
-    outputs:
-      language: ${{ steps.get-language.outputs.language }}
-    steps:
-      - name: Parse language from tag
-        id: get-language
-        run: |
-          tag=${{ inputs.tag }}
-          language=$(echo $tag | awk -F'-' '{print $NF}')
-          if [[ ! "$language" =~ ^(java|ruby|python|dotnet|node)$ ]]; then
-            language="all"
-          fi
-          echo "language=$language" > $GITHUB_OUTPUT
-
-  java-docs:
-    runs-on: ubuntu-latest
-    needs: determine-language
-    steps:
-      - name: Checkout the tag
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.tag }}
-      - name: Prep git
-        run: |
-          git config --local user.email "selenium-ci@users.noreply.github.com"
-          git config --local user.name "Selenium CI Bot"
-      - name: Setup Java
-        uses: actions/setup-java@v4
-        with:
-          java-version: 17
-          distribution: 'temurin'
-      - name: Update Documentation
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'java'
-        run: ./go java:docs
-      - name: Create patch for changes
-        run: |
-          git format-patch -1 HEAD --stdout > java-docs.patch
-      - name: Upload patch
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'java'
-        uses: actions/upload-artifact@v4
-        with:
-          name: java-docs-patch
-          path: java-docs.patch
-
-  ruby-docs:
+  build-docs:
     runs-on: ubuntu-latest
-    needs: determine-language
     steps:
-      - name: Checkout the tag
+      - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          ref: ${{ inputs.tag }}
-      - name: Prep git
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.ref || inputs.sha }}
+      - name: Setup git
         run: |
           git config --local user.email "selenium-ci@users.noreply.github.com"
           git config --local user.name "Selenium CI Bot"
+      - name: Setup curl for Ubuntu
+        run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev
       - name: Setup Java
         uses: actions/setup-java@v4
         with:
           java-version: 17
           distribution: 'temurin'
-      - name: Setup curl for Ubuntu
-        run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev
-      - name: Update Documentation
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'ruby'
-        run: ./go rb:docs
-      - name: Create patch for changes
-        run: |
-          git format-patch -1 HEAD --stdout > ruby-docs.patch
-      - name: Upload patch
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'ruby'
-        uses: actions/upload-artifact@v4
-        with:
-          name: ruby-docs-patch
-          path: ruby-docs.patch
-
-  python-docs:
-    needs: determine-language
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the tag
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.tag }}
-      - name: Prep git
-        run: |
-          git config --local user.email "selenium-ci@users.noreply.github.com"
-          git config --local user.name "Selenium CI Bot"
       - name: Set up Python 3.9
+        if: ${{ inputs.language == 'all' || inputs.language == 'py' }}
         uses: actions/setup-python@v5
         with:
           python-version: 3.9
       - name: Install dependencies
+        if: ${{ inputs.language == 'all' || inputs.language == 'py' }}
         run: |
           python -m pip install --upgrade pip
           pip install tox
-      - name: Update Documentation
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'python'
-        run: ./go py:docs
-      - name: Create patch for changes
-        run: |
-          git format-patch -1 HEAD --stdout > python-docs.patch
-      - name: Upload patch
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'python'
-        uses: actions/upload-artifact@v4
-        with:
-          name: python-docs-patch
-          path: python-docs.patch
-
-  dotnet-docs:
-    needs: determine-language
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the tag
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.tag }}
-      - name: Prep git
-        run: |
-          git config --local user.email "selenium-ci@users.noreply.github.com"
-          git config --local user.name "Selenium CI Bot"
-      - name: Update Documentation
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'dotnet'
-        run: ./go dotnet:docs
-      - name: Create patch for changes
-        run: |
-          git format-patch -1 HEAD --stdout > dotnet-docs.patch
-      - name: Upload patch
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'dotnet'
-        uses: actions/upload-artifact@v4
-        with:
-          name: dotnet-docs-patch
-          path: dotnet-docs.patch
-
-  node-docs:
-    needs: determine-language
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the tag
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.tag }}
-      - name: Prep git
-        run: |
-          git config --local user.email "selenium-ci@users.noreply.github.com"
-          git config --local user.name "Selenium CI Bot"
       - name: Install npm dependencies
+        if: ${{ inputs.language == 'all' || inputs.language == 'node' }}
         run: |
           npm install
           npm install --prefix javascript/node/selenium-webdriver
       - name: Update Documentation
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'node'
-        run: ./go node:docs
-      - name: Create patch for changes
-        run: |
-          git format-patch -1 HEAD --stdout > node-docs.patch
-      - name: Upload patch
-        if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'node'
-        uses: actions/upload-artifact@v4
-        with:
-          name: node-docs-patch
-          path: node-docs.patch
+        run: ./go ${{ inputs.language }}:docs
 
-  merge-patches:
-    runs-on: ubuntu-latest
-    needs: [java-docs, ruby-docs, python-docs, dotnet-docs, node-docs]
-    steps:
-      - name: Checkout  documentation branch
-        uses: actions/checkout@v4
-        with:
-          ref: 'gh-pages'
-          fetch-depth: 0
-          fetch-tags: true
-      - name: Create and checkout new branch
-        run: |
-          git config --local user.email "selenium-ci@users.noreply.github.com"
-          git config --local user.name "Selenium CI Bot"
-          git checkout -b api-docs-${{ inputs.tag }}
-      - name: Download all patches
-        uses: actions/download-artifact@v4
-        with:
-          path: patches/
-          merge-multiple: true
-      - name: Show downloaded patches
-        run: ls -lah patches/
-      - name: Apply patches
-        run: |
-          for patch in patches/*.patch; do
-            git am < "$patch"
-          done
-          rm -rf patches/
-      - name: Push Branch
-        run: git push origin api-docs-${{ inputs.tag }}
       - name: Documentation Pull Request
         uses: peter-evans/create-pull-request@v6
         with:
           token: ${{ secrets.SELENIUM_CI_TOKEN }}
           author: Selenium CI Bot <selenium-ci@users.noreply.github.com>
           delete-branch: true
-          branch: api-docs-${{ inputs.tag }}
+          branch: api-docs-${{ inputs.version }}-${{ inputs.language }}
           base: gh-pages
-          title: Update documentation for ${{ inputs.tag }}
+          title: Update documentation for Selenium ${{ inputs.version }} (${{ inputs.language }})
           body: |
-            This PR updates the API documentation for all bindings
-            based on the provided tag name.
+            This PR updates the API documentation for **${{ inputs.language }}** language bindings to version **${{ inputs.version }}**.
 
             - Auto-generated by [create-pull-request][1]
 

Rakefile

@@ -484,12 +484,15 @@ namespace :node do
 
   desc 'Generate Node documentation'
   task :docs, [:skip_update] do |_task, arguments|
+    abort('Aborting documentation update: nightly versions should not update docs.') if node_version.include?('nightly')
+
+    puts 'Generating Node documentation'
     FileUtils.rm_rf('build/docs/api/javascript/')
     begin
-      sh 'npm run generate-docs --prefix javascript/node/selenium-webdriver || true', verbose: true
-    rescue StandardError
-      puts 'Ensure that npm is installed on your system'
-      raise
+      sh 'npm install --prefix javascript/node/selenium-webdriver', verbose: true
+      sh 'npm run generate-docs --prefix javascript/node/selenium-webdriver', verbose: true
+    rescue StandardError => e
+      puts "Node documentation generation contains errors; continuing... #{e.message}"
     end
 
     update_gh_pages unless arguments[:skip_update]
@@ -576,6 +579,11 @@ namespace :py do
 
   desc 'Generate Python documentation'
   task :docs, [:skip_update] do |_task, arguments|
+    if python_version.match?(/^\d+\.\d+\.\d+\.\d+$/)
+      abort('Aborting documentation update: nightly versions should not update docs.')
+    end
+    puts 'Generating Python documentation'
+
     FileUtils.rm_rf('build/docs/api/py/')
     FileUtils.rm_rf('build/docs/doctrees/')
     begin
@@ -714,6 +722,9 @@ namespace :rb do
 
   desc 'Generate Ruby documentation'
   task :docs, [:skip_update] do |_task, arguments|
+    abort('Aborting documentation update: nightly versions should not update docs.') if ruby_version.include?('nightly')
+    puts 'Generating Ruby documentation'
+
     FileUtils.rm_rf('build/docs/api/rb/')
     Bazel.execute('run', [], '//rb:docs')
     FileUtils.mkdir_p('build/docs/api')
@@ -801,6 +812,11 @@ namespace :dotnet do
 
   desc 'Generate .NET documentation'
   task :docs, [:skip_update] do |_task, arguments|
+    if dotnet_version.include?('nightly')
+      abort('Aborting documentation update: nightly versions should not update docs.')
+    end
+
+    puts 'Generating .NET documentation'
     FileUtils.rm_rf('build/docs/api/dotnet/')
     begin
       # Pinning to 2.78.2 to avoid breaking changes in newer versions
@@ -907,6 +923,11 @@ namespace :java do
 
   desc 'Generate Java documentation'
   task :docs, [:skip_update] do |_task, arguments|
+    if java_version.include?('SNAPSHOT')
+      abort('Aborting documentation update: snapshot versions should not update docs.')
+    end
+
+    puts 'Generating Java documentation'
     Rake::Task['javadocs'].invoke
 
     update_gh_pages unless arguments[:skip_update]
@@ -1175,26 +1196,34 @@ def updated_version(current, desired = nil, nightly = nil)
   end
 end
 
-def update_gh_pages
-  @git.fetch('origin', {ref: 'gh-pages'})
-  @git.checkout('gh-pages', force: true)
+def update_gh_pages(force: true)
+  puts 'Switching to gh-pages branch...'
+  @git.fetch('https://github.com/seleniumhq/selenium.git', {ref: 'gh-pages'})
+
+  unless force
+    puts 'Stashing current changes before checkout...'
+    Git::Stash.new(@git, 'stash wip')
+  end
+
+  @git.checkout('gh-pages', force: force)
+
+  updated = false
 
   %w[java rb py dotnet javascript].each do |language|
-    next unless Dir.exist?("build/docs/api/#{language}") && !Dir.empty?("build/docs/api/#{language}")
+    source = "build/docs/api/#{language}"
+    destination = "docs/api/#{language}"
 
-    FileUtils.rm_rf("docs/api/#{language}")
-    FileUtils.mv("build/docs/api/#{language}", "docs/api/#{language}")
+    next unless Dir.exist?(source) && !Dir.empty?(source)
 
-    commit!("updating #{language} API docs", ["docs/api/#{language}/"])
+    puts "Updating documentation for #{language}..."
+    FileUtils.rm_rf(destination)
+    FileUtils.mv(source, destination)
+
+    @git.add(destination)
+    updated = true
   end
-end
 
-def restore_git(origin_reference)
-  puts 'Stashing docs changes for gh-pages'
-  Git::Stash.new(@git, 'docs changes for gh-pages')
-  puts "Checking out originating branch/tag — #{origin_reference}"
-  @git.checkout(origin_reference)
-  false
+  puts(updated ? 'Documentation staged. Ready for commit.' : 'No documentation changes found.')
 end
 
 def previous_tag(current_version, language = nil)