Skip to content

Commit 995735d

Browse files
titusfortnertitusfortner
committed
[build] add workflow to create a branch with documentation updates
1 parent 566bac6 commit 995735d

File tree

2 files changed

+142
-85
lines changed

2 files changed

+142
-85
lines changed

‎.github/workflows/update-documentation.yml‎

Lines changed: 131 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,29 @@ jobs:
1919
uses: actions/checkout@v4
2020
with:
2121
ref: ${{ inputs.tag }}
22+
- name: Prep git
23+
run: |
24+
git config --local user.email "[email protected]"
25+
git config --local user.name "Selenium CI Bot"
26+
- name: Get updated Rakefile
27+
run: |
28+
git fetch origin auto_docs
29+
git checkout origin/auto_docs -- Rakefile
2230
- name: Setup Java
2331
uses: actions/setup-java@v3
2432
with:
2533
java-version: 17
2634
distribution: 'temurin'
2735
- name: Update Documentation
28-
run: ./go java:docs[true]
36+
run: ./go java:docs
37+
- name: Create patch for changes
38+
run: |
39+
git format-patch -1 HEAD --stdout > java-docs.patch
40+
- name: Upload patch
41+
uses: actions/upload-artifact@v2
42+
with:
43+
name: java-docs-patch
44+
path: java-docs.patch
2945

3046
ruby-docs:
3147
runs-on: ubuntu-latest
@@ -34,13 +50,29 @@ jobs:
3450
uses: actions/checkout@v4
3551
with:
3652
ref: ${{ inputs.tag }}
53+
- name: Prep git
54+
run: |
55+
git config --local user.email "[email protected]"
56+
git config --local user.name "Selenium CI Bot"
57+
- name: Get updated Rakefile
58+
run: |
59+
git fetch origin auto_docs
60+
git checkout origin/auto_docs -- Rakefile
3761
- name: Setup Java
3862
uses: actions/setup-java@v3
3963
with:
4064
java-version: 17
4165
distribution: 'temurin'
4266
- name: Update Documentation
43-
run: ./go ruby:docs[true]
67+
run: ./go rb:docs
68+
- name: Create patch for changes
69+
run: |
70+
git format-patch -1 HEAD --stdout > ruby-docs.patch
71+
- name: Upload patch
72+
uses: actions/upload-artifact@v2
73+
with:
74+
name: ruby-docs-patch
75+
path: ruby-docs.patch
4476

4577
python-docs:
4678
runs-on: ubuntu-latest
@@ -49,12 +81,32 @@ jobs:
4981
uses: actions/checkout@v4
5082
with:
5183
ref: ${{ inputs.tag }}
84+
- name: Prep git
85+
run: |
86+
git config --local user.email "[email protected]"
87+
git config --local user.name "Selenium CI Bot"
88+
- name: Get updated Rakefile
89+
run: |
90+
git fetch origin auto_docs
91+
git checkout origin/auto_docs -- Rakefile
5292
- name: Set up Python 3.8
5393
uses: actions/setup-python@v4
5494
with:
5595
python-version: 3.8
96+
- name: Install dependencies
97+
run: |
98+
python -m pip install --upgrade pip
99+
pip install tox
56100
- name: Update Documentation
57-
run: ./go py:docs[true]
101+
run: ./go py:docs
102+
- name: Create patch for changes
103+
run: |
104+
git format-patch -1 HEAD --stdout > python-docs.patch
105+
- name: Upload patch
106+
uses: actions/upload-artifact@v2
107+
with:
108+
name: python-docs-patch
109+
path: python-docs.patch
58110

59111
dotnet-docs:
60112
runs-on: ubuntu-latest
@@ -63,12 +115,28 @@ jobs:
63115
uses: actions/checkout@v4
64116
with:
65117
ref: ${{ inputs.tag }}
118+
- name: Prep git
119+
run: |
120+
git config --local user.email "[email protected]"
121+
git config --local user.name "Selenium CI Bot"
122+
- name: Get updated Rakefile
123+
run: |
124+
git fetch origin auto_docs
125+
git checkout origin/auto_docs -- Rakefile
66126
- name: Install specific version of DocFX tool
67127
# Pinning to 2.75.3 to avoid breaking changes in newer versions
68128
# See https://github.com/dotnet/docfx/issues/9855
69129
run: dotnet tool install --global --version 2.75.3 docfx
70130
- name: Update Documentation
71-
run: ./go dotnet:docs[true]
131+
run: ./go dotnet:docs
132+
- name: Create patch for changes
133+
run: |
134+
git format-patch -1 HEAD --stdout > dotnet-docs.patch
135+
- name: Upload patch
136+
uses: actions/upload-artifact@v2
137+
with:
138+
name: dotnet-docs-patch
139+
path: dotnet-docs.patch
72140

73141
node-docs:
74142
runs-on: ubuntu-latest
@@ -77,9 +145,67 @@ jobs:
77145
uses: actions/checkout@v4
78146
with:
79147
ref: ${{ inputs.tag }}
148+
- name: Prep git
149+
run: |
150+
git config --local user.email "[email protected]"
151+
git config --local user.name "Selenium CI Bot"
152+
- name: Get updated Rakefile
153+
run: |
154+
git fetch origin auto_docs
155+
git checkout origin/auto_docs -- Rakefile
80156
- name: Install npm dependencies
81157
run: |
82158
npm install
83159
npm install --prefix javascript/node/selenium-webdriver
84160
- name: Update Documentation
85-
run: ./go node:docs[true]
161+
run: ./go node:docs
162+
- name: Create patch for changes
163+
run: |
164+
git format-patch -1 HEAD --stdout > node-docs.patch
165+
- name: Upload patch
166+
uses: actions/upload-artifact@v2
167+
with:
168+
name: node-docs-patch
169+
path: node-docs.patch
170+
171+
merge-patches:
172+
runs-on: ubuntu-latest
173+
needs: [java-docs, ruby-docs, python-docs, dotnet-docs, node-docs]
174+
steps:
175+
- name: Checkout documentation branch
176+
uses: actions/checkout@v4
177+
with:
178+
ref: 'gh-pages'
179+
- name: Create and checkout new branch
180+
run: |
181+
git config --local user.email "[email protected]"
182+
git config --local user.name "Selenium CI Bot"
183+
git checkout -b api-docs-${{ inputs.tag }}
184+
- name: Download patches
185+
uses: actions/download-artifact@v2
186+
with:
187+
name: java-docs-patch
188+
path: patches/
189+
- uses: actions/download-artifact@v2
190+
with:
191+
name: ruby-docs-patch
192+
path: patches/
193+
- uses: actions/download-artifact@v2
194+
with:
195+
name: python-docs-patch
196+
path: patches/
197+
- uses: actions/download-artifact@v2
198+
with:
199+
name: dotnet-docs-patch
200+
path: patches/
201+
- uses: actions/download-artifact@v2
202+
with:
203+
name: node-docs-patch
204+
path: patches/
205+
- name: Apply patches
206+
run: |
207+
for patch in patches/*.patch; do
208+
git am < "$patch"
209+
done
210+
- name: Push Branch
211+
run: git push origin api-docs-${{ inputs.tag }}

‎Rakefile‎

Lines changed: 11 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -466,10 +466,7 @@ namespace :node do
466466
raise
467467
end
468468

469-
unless arguments[:skip_update]
470-
puts 'Updating JavaScript documentation'
471-
puts update_gh_pages ? 'JavaScript Docs updated!' : 'JavaScript Doc update cancelled'
472-
end
469+
update_gh_pages unless arguments[:skip_update]
473470
end
474471

475472
desc 'Update JavaScript changelog'
@@ -563,10 +560,7 @@ namespace :py do
563560
raise
564561
end
565562

566-
unless arguments[:skip_update]
567-
puts 'Updating Python documentation'
568-
puts update_gh_pages ? 'Python Docs updated!' : 'Python Doc update cancelled'
569-
end
563+
update_gh_pages unless arguments[:skip_update]
570564
end
571565

572566
desc 'Install Python wheel locally'
@@ -700,10 +694,7 @@ namespace :rb do
700694
FileUtils.mkdir_p('build/docs/api')
701695
FileUtils.cp_r('bazel-bin/rb/docs.sh.runfiles/_main/docs/api/rb/.', 'build/docs/api/rb')
702696

703-
unless arguments[:skip_update]
704-
puts 'Updating Ruby documentation'
705-
puts update_gh_pages ? 'Ruby Docs updated!' : 'Ruby Doc update cancelled'
706-
end
697+
update_gh_pages unless arguments[:skip_update]
707698
end
708699

709700
desc 'Update Ruby changelog'
@@ -810,10 +801,7 @@ namespace :dotnet do
810801
end
811802
end
812803

813-
unless arguments[:skip_update]
814-
puts 'Updating .NET documentation'
815-
puts update_gh_pages ? '.NET Docs updated!' : '.NET Doc update cancelled'
816-
end
804+
update_gh_pages unless arguments[:skip_update]
817805
end
818806

819807
desc 'Update .NET changelog'
@@ -896,10 +884,7 @@ namespace :java do
896884
task :docs, [:skip_update] do |_task, arguments|
897885
Rake::Task['javadocs'].invoke
898886

899-
unless arguments[:skip_update]
900-
puts 'Updating Java documentation'
901-
puts update_gh_pages ? 'Java Docs updated!' : 'Java Doc update cancelled'
902-
end
887+
update_gh_pages unless arguments[:skip_update]
903888
end
904889

905890
desc 'Update Maven dependencies'
@@ -1013,16 +998,13 @@ end
1013998
namespace :all do
1014999
desc 'Update all API Documentation'
10151000
task :docs do
1016-
FileUtils.rm_rf('build/docs/api')
1017-
10181001
Rake::Task['java:docs'].invoke(true)
10191002
Rake::Task['py:docs'].invoke(true)
10201003
Rake::Task['rb:docs'].invoke(true)
10211004
Rake::Task['dotnet:docs'].invoke(true)
10221005
Rake::Task['node:docs'].invoke(true)
10231006

1024-
puts 'Updating All API Docs'
1025-
puts update_gh_pages ? 'AP Docs updated!' : 'API Doc update cancelled'
1007+
update_gh_pages
10261008
end
10271009

10281010
desc 'Build all artifacts for all language bindings'
@@ -1052,7 +1034,7 @@ namespace :all do
10521034
Rake::Task['rb:release'].invoke(*args)
10531035
Rake::Task['dotnet:release'].invoke(*args)
10541036
Rake::Task['node:release'].invoke(*args)
1055-
Rake::Task['all:docs'].invoke
1037+
10561038
Rake::Task['all:version'].invoke('nightly')
10571039

10581040
puts 'Committing nightly version updates'
@@ -1164,70 +1146,19 @@ def updated_version(current, desired = nil, nightly = nil)
11641146
end
11651147
end
11661148

1167-
# TODO: make this less insane
1168-
# rubocop:disable all
11691149
def update_gh_pages
1170-
origin_reference = @git.current_branch
1171-
origin_reference ||= begin
1172-
# This allows updating docs from a tagged commit instead of a branch
1173-
puts 'commit is not at HEAD, checking for matching tag'
1174-
tag = @git.tags.detect { |t| t.sha == @git.revparse('HEAD') }
1175-
tag ? tag.name : raise(StandardError, 'Must be on a tagged commit or at the HEAD of a branch to update API Docs')
1176-
end
1177-
1178-
puts 'Checking out gh-pages'
1179-
begin
1180-
@git.checkout('gh-pages')
1181-
rescue Git::FailedError => e
1182-
# This happens when the working directory is not clean and things need to be stashed or committed
1183-
line = e.message.lines[2].gsub('output: "error: ', '')
1184-
puts line.gsub('\t', "\t").split('\n')[0...-2].join("\n")
1185-
# TODO: we could offer to automatically fix with a stash, but there may be edge cases
1186-
print 'Manually Fix and Retry? (Y/n):'
1187-
response = $stdin.gets.chomp.downcase
1188-
return false unless %w[y yes].include?(response)
1189-
1190-
retry
1191-
end
1192-
1193-
puts 'Updating gh-pages branch from upstream repository'
1194-
begin
1195-
@git.pull
1196-
rescue Git::FailedError => e
1197-
# This happens when upstream is not already set
1198-
line = e.message.lines[2].gsub('output: "error: ', '')
1199-
puts line.gsub('\t', "\t").split('\n').delete_if(&:empty?)[-2...-1].join("\n")
1200-
print 'Manually Fix and Retry? (Y/n):'
1201-
response = $stdin.gets.chomp.downcase
1202-
return restore_git(origin_reference) unless %w[y yes].include?(response)
1203-
1204-
retry
1205-
end
1150+
@git.fetch('origin', {ref: 'gh-pages'})
1151+
@git.checkout('gh-pages', force: true)
12061152

12071153
%w[java rb py dotnet javascript].each do |language|
12081154
next unless Dir.exist?("build/docs/api/#{language}") && !Dir.empty?("build/docs/api/#{language}")
12091155

1210-
puts "Deleting #{language} directory in docs/api since corresponding directory in build/docs/api is not empty"
12111156
FileUtils.rm_rf("docs/api/#{language}")
1212-
puts 'Moving documentation files from untracked build directory to tracked docs directory'
12131157
FileUtils.mv("build/docs/api/#{language}", "docs/api/#{language}")
1214-
end
1215-
1216-
print 'Do you want to commit the changes? (Y/n): '
1217-
response = $stdin.gets.chomp.downcase
1218-
return restore_git(origin_reference) unless %w[y yes].include?(response)
12191158

1220-
puts 'Committing changes'
1221-
commit!('updating all API docs', ['docs/api/'])
1222-
1223-
puts 'Pushing changes to upstream repository'
1224-
@git.push
1225-
1226-
puts "Checking out originating branch/tag — #{origin_reference}"
1227-
@git.checkout(origin_reference)
1228-
true
1159+
commit!("updating #{language} API docs", ["docs/api/#{language}/"])
1160+
end
12291161
end
1230-
# rubocop:disable all
12311162

12321163
def restore_git(origin_reference)
12331164
puts 'Stashing docs changes for gh-pages'

0 commit comments

Comments
 (0)