Skip to content

Commit

Permalink
[build] add workflow to create a branch with documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@titusfortner
titusfortner committed Jun 21, 2024
1 parent 566bac6 commit 995735d
Show file tree
Hide file tree
Showing 2 changed files with 142 additions and 85 deletions.
136 changes: 131 additions & 5 deletions .github/workflows/update-documentation.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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 }}
91 changes: 11 additions & 80 deletions Rakefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down

0 comments on commit 995735d

Please sign in to comment.