From 995735d9fb0c9253811f1a247ecd5a4ccec18ac5 Mon Sep 17 00:00:00 2001 From: titusfortner Date: Fri, 21 Jun 2024 11:47:28 -0500 Subject: [PATCH] [build] add workflow to create a branch with documentation updates --- .github/workflows/update-documentation.yml | 136 ++++++++++++++++++++- Rakefile | 91 ++------------ 2 files changed, 142 insertions(+), 85 deletions(-) diff --git a/.github/workflows/update-documentation.yml b/.github/workflows/update-documentation.yml index 02166dc7a6d34..7be2eccbcf070 100644 --- a/.github/workflows/update-documentation.yml +++ b/.github/workflows/update-documentation.yml @@ -19,13 +19,29 @@ jobs: 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: Get updated Rakefile + run: | + git fetch origin auto_docs + git checkout origin/auto_docs -- Rakefile - name: Setup Java uses: actions/setup-java@v3 with: java-version: 17 distribution: 'temurin' - name: Update Documentation - run: ./go java:docs[true] + run: ./go java:docs + - name: Create patch for changes + run: | + git format-patch -1 HEAD --stdout > java-docs.patch + - name: Upload patch + uses: actions/upload-artifact@v2 + with: + name: java-docs-patch + path: java-docs.patch ruby-docs: runs-on: ubuntu-latest @@ -34,13 +50,29 @@ jobs: 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: Get updated Rakefile + run: | + git fetch origin auto_docs + git checkout origin/auto_docs -- Rakefile - name: Setup Java uses: actions/setup-java@v3 with: java-version: 17 distribution: 'temurin' - name: Update Documentation - run: ./go ruby:docs[true] + run: ./go rb:docs + - name: Create patch for changes + run: | + git format-patch -1 HEAD --stdout > ruby-docs.patch + - name: Upload patch + uses: actions/upload-artifact@v2 + with: + name: ruby-docs-patch + path: ruby-docs.patch python-docs: runs-on: ubuntu-latest @@ -49,12 +81,32 @@ jobs: 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: Get updated Rakefile + run: | + git fetch origin auto_docs + git checkout origin/auto_docs -- Rakefile - name: Set up Python 3.8 uses: actions/setup-python@v4 with: python-version: 3.8 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install tox - name: Update Documentation - run: ./go py:docs[true] + run: ./go py:docs + - name: Create patch for changes + run: | + git format-patch -1 HEAD --stdout > python-docs.patch + - name: Upload patch + uses: actions/upload-artifact@v2 + with: + name: python-docs-patch + path: python-docs.patch dotnet-docs: runs-on: ubuntu-latest @@ -63,12 +115,28 @@ jobs: 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: Get updated Rakefile + run: | + git fetch origin auto_docs + git checkout origin/auto_docs -- Rakefile - name: Install specific version of DocFX tool # Pinning to 2.75.3 to avoid breaking changes in newer versions # See https://github.com/dotnet/docfx/issues/9855 run: dotnet tool install --global --version 2.75.3 docfx - name: Update Documentation - run: ./go dotnet:docs[true] + run: ./go dotnet:docs + - name: Create patch for changes + run: | + git format-patch -1 HEAD --stdout > dotnet-docs.patch + - name: Upload patch + uses: actions/upload-artifact@v2 + with: + name: dotnet-docs-patch + path: dotnet-docs.patch node-docs: runs-on: ubuntu-latest @@ -77,9 +145,67 @@ jobs: 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: Get updated Rakefile + run: | + git fetch origin auto_docs + git checkout origin/auto_docs -- Rakefile - name: Install npm dependencies run: | npm install npm install --prefix javascript/node/selenium-webdriver - name: Update Documentation - run: ./go node:docs[true] + run: ./go node:docs + - name: Create patch for changes + run: | + git format-patch -1 HEAD --stdout > node-docs.patch + - name: Upload patch + uses: actions/upload-artifact@v2 + with: + name: node-docs-patch + path: node-docs.patch + + 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' + - 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 patches + uses: actions/download-artifact@v2 + with: + name: java-docs-patch + path: patches/ + - uses: actions/download-artifact@v2 + with: + name: ruby-docs-patch + path: patches/ + - uses: actions/download-artifact@v2 + with: + name: python-docs-patch + path: patches/ + - uses: actions/download-artifact@v2 + with: + name: dotnet-docs-patch + path: patches/ + - uses: actions/download-artifact@v2 + with: + name: node-docs-patch + path: patches/ + - name: Apply patches + run: | + for patch in patches/*.patch; do + git am < "$patch" + done + - name: Push Branch + run: git push origin api-docs-${{ inputs.tag }} diff --git a/Rakefile b/Rakefile index 2a8336282900d..31208691370f9 100644 --- a/Rakefile +++ b/Rakefile @@ -466,10 +466,7 @@ namespace :node do raise end - unless arguments[:skip_update] - puts 'Updating JavaScript documentation' - puts update_gh_pages ? 'JavaScript Docs updated!' : 'JavaScript Doc update cancelled' - end + update_gh_pages unless arguments[:skip_update] end desc 'Update JavaScript changelog' @@ -563,10 +560,7 @@ namespace :py do raise end - unless arguments[:skip_update] - puts 'Updating Python documentation' - puts update_gh_pages ? 'Python Docs updated!' : 'Python Doc update cancelled' - end + update_gh_pages unless arguments[:skip_update] end desc 'Install Python wheel locally' @@ -700,10 +694,7 @@ namespace :rb do FileUtils.mkdir_p('build/docs/api') FileUtils.cp_r('bazel-bin/rb/docs.sh.runfiles/_main/docs/api/rb/.', 'build/docs/api/rb') - unless arguments[:skip_update] - puts 'Updating Ruby documentation' - puts update_gh_pages ? 'Ruby Docs updated!' : 'Ruby Doc update cancelled' - end + update_gh_pages unless arguments[:skip_update] end desc 'Update Ruby changelog' @@ -810,10 +801,7 @@ namespace :dotnet do end end - unless arguments[:skip_update] - puts 'Updating .NET documentation' - puts update_gh_pages ? '.NET Docs updated!' : '.NET Doc update cancelled' - end + update_gh_pages unless arguments[:skip_update] end desc 'Update .NET changelog' @@ -896,10 +884,7 @@ namespace :java do task :docs, [:skip_update] do |_task, arguments| Rake::Task['javadocs'].invoke - unless arguments[:skip_update] - puts 'Updating Java documentation' - puts update_gh_pages ? 'Java Docs updated!' : 'Java Doc update cancelled' - end + update_gh_pages unless arguments[:skip_update] end desc 'Update Maven dependencies' @@ -1013,16 +998,13 @@ end namespace :all do desc 'Update all API Documentation' task :docs do - FileUtils.rm_rf('build/docs/api') - Rake::Task['java:docs'].invoke(true) Rake::Task['py:docs'].invoke(true) Rake::Task['rb:docs'].invoke(true) Rake::Task['dotnet:docs'].invoke(true) Rake::Task['node:docs'].invoke(true) - puts 'Updating All API Docs' - puts update_gh_pages ? 'AP Docs updated!' : 'API Doc update cancelled' + update_gh_pages end desc 'Build all artifacts for all language bindings' @@ -1052,7 +1034,7 @@ namespace :all do Rake::Task['rb:release'].invoke(*args) Rake::Task['dotnet:release'].invoke(*args) Rake::Task['node:release'].invoke(*args) - Rake::Task['all:docs'].invoke + Rake::Task['all:version'].invoke('nightly') puts 'Committing nightly version updates' @@ -1164,70 +1146,19 @@ def updated_version(current, desired = nil, nightly = nil) end end -# TODO: make this less insane -# rubocop:disable all def update_gh_pages - origin_reference = @git.current_branch - origin_reference ||= begin - # This allows updating docs from a tagged commit instead of a branch - puts 'commit is not at HEAD, checking for matching tag' - tag = @git.tags.detect { |t| t.sha == @git.revparse('HEAD') } - tag ? tag.name : raise(StandardError, 'Must be on a tagged commit or at the HEAD of a branch to update API Docs') - end - - puts 'Checking out gh-pages' - begin - @git.checkout('gh-pages') - rescue Git::FailedError => e - # This happens when the working directory is not clean and things need to be stashed or committed - line = e.message.lines[2].gsub('output: "error: ', '') - puts line.gsub('\t', "\t").split('\n')[0...-2].join("\n") - # TODO: we could offer to automatically fix with a stash, but there may be edge cases - print 'Manually Fix and Retry? (Y/n):' - response = $stdin.gets.chomp.downcase - return false unless %w[y yes].include?(response) - - retry - end - - puts 'Updating gh-pages branch from upstream repository' - begin - @git.pull - rescue Git::FailedError => e - # This happens when upstream is not already set - line = e.message.lines[2].gsub('output: "error: ', '') - puts line.gsub('\t', "\t").split('\n').delete_if(&:empty?)[-2...-1].join("\n") - print 'Manually Fix and Retry? (Y/n):' - response = $stdin.gets.chomp.downcase - return restore_git(origin_reference) unless %w[y yes].include?(response) - - retry - end + @git.fetch('origin', {ref: 'gh-pages'}) + @git.checkout('gh-pages', force: true) %w[java rb py dotnet javascript].each do |language| next unless Dir.exist?("build/docs/api/#{language}") && !Dir.empty?("build/docs/api/#{language}") - puts "Deleting #{language} directory in docs/api since corresponding directory in build/docs/api is not empty" FileUtils.rm_rf("docs/api/#{language}") - puts 'Moving documentation files from untracked build directory to tracked docs directory' FileUtils.mv("build/docs/api/#{language}", "docs/api/#{language}") - end - - print 'Do you want to commit the changes? (Y/n): ' - response = $stdin.gets.chomp.downcase - return restore_git(origin_reference) unless %w[y yes].include?(response) - puts 'Committing changes' - commit!('updating all API docs', ['docs/api/']) - - puts 'Pushing changes to upstream repository' - @git.push - - puts "Checking out originating branch/tag — #{origin_reference}" - @git.checkout(origin_reference) - true + commit!("updating #{language} API docs", ["docs/api/#{language}/"]) + end end -# rubocop:disable all def restore_git(origin_reference) puts 'Stashing docs changes for gh-pages'