Skip to content

Commit 1b49c5a

Browse files
kggilmerkggilmer
authored
chore: API service docs generation (#405)
1 parent 636ddb8 commit 1b49c5a

File tree

3 files changed

+240
-2
lines changed

3 files changed

+240
-2
lines changed

‎.github/workflows/api-docs.yml‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
name: API Docs
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
release-tag:
7+
description: The aws-sdk-kotlin release tag
8+
required: true
9+
release:
10+
types: [published]
11+
12+
jobs:
13+
smithy-kotlin-docs:
14+
runs-on: ubuntu-latest
15+
outputs:
16+
source-ref: ${{ steps.source-ref.outputs.build_ref }}
17+
steps:
18+
- name: Consolidate source ref
19+
id: source-ref
20+
run: |
21+
if [ -z "${{ github.event.inputs.release-tag }}" ]; then
22+
echo ::set-output name=build_ref::"$GITHUB_REF"
23+
else
24+
echo ::set-output name=build_ref::"${{ github.event.inputs.release-tag }}"
25+
fi
26+
- name: Checkout aws-sdk-kotlin sources
27+
uses: actions/checkout@v2
28+
with:
29+
ref: ${{ steps.source-ref.outputs.build_ref }}
30+
path: aws-sdk-kotlin
31+
- name: Get repo owner and version
32+
id: repo-owner
33+
run: |
34+
owner=$(echo ${GITHUB_REPOSITORY} | cut -d/ -f1)
35+
echo ::set-output name=repo-owner::"$owner"
36+
smithy_kotlin_version=$(cat aws-sdk-kotlin/gradle.properties | grep smithyKotlinVersion | cut -d= -f2)
37+
echo ::set-output name=smithy_kotlin_version::"v$smithy_kotlin_version"
38+
- name: Checkout smithy-kotlin sources
39+
uses: actions/checkout@v2
40+
with:
41+
repository: ${{ steps.repo-owner.outputs.repo-owner }}/smithy-kotlin
42+
ref: ${{ steps.repo-owner.outputs.smithy_kotlin_version }}
43+
path: smithy-kotlin
44+
- name: Build upstream docs
45+
id: smithy-kotlin-build
46+
run: |
47+
cd smithy-kotlin
48+
49+
# Dokka 1.5.3 requires additional memory to generate docs
50+
printf "\norg.gradle.jvmargs=-Xmx6g -XX:MaxPermSize=6g" >> gradle.properties
51+
52+
./gradlew dokkaHtmlMultiModule
53+
mkdir smithy-kotlin-docs
54+
mv build/dokka/htmlMultiModule/* smithy-kotlin-docs/
55+
- name: Upload Smithy-Kotlin Doc Artifact
56+
uses: actions/upload-artifact@v2
57+
with:
58+
name: smithy-kotlin-docs
59+
path: smithy-kotlin/smithy-kotlin-docs
60+
61+
api-doc-gen-parallel:
62+
runs-on: ubuntu-latest
63+
needs: smithy-kotlin-docs
64+
strategy:
65+
matrix:
66+
service-prefix: [ a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z ]
67+
steps:
68+
- name: Checkout sources
69+
uses: actions/checkout@v2
70+
with:
71+
ref: ${{ needs.smithy-kotlin-docs.outputs.source-ref }}
72+
- name: Download smithy-kotlin artifacts
73+
uses: actions/download-artifact@v2
74+
with:
75+
name: smithy-kotlin-docs
76+
path: smithy-kotlin-docs
77+
- name: Generate API Docs
78+
id: gen-docs
79+
run: |
80+
# Do not generate SDKs for the following unsupported SDKs
81+
excluded_services=("transcribestreaming" "timestreamwrite" "timestreamquery")
82+
83+
# Resource mgmt optimization for Dokka
84+
printf "\norg.gradle.daemon=false" >> gradle.properties
85+
86+
# do not execute following loop if no files w prefix
87+
shopt -s nullglob
88+
89+
# configure path to smithy-kotlin's package-list
90+
smithy_kotlin_package_list_path="$(pwd)/smithy-kotlin-docs/package-list"
91+
92+
# Track if docs were generated in this segment of job run.
93+
docs_generated=false
94+
95+
# Iterate over service models, extract the name and codegen each SDK discretely
96+
for aws_model_file in codegen/sdk/aws-models/${{ matrix.service-prefix }}*.json
97+
do
98+
# delete src for any previously generated SDK
99+
git clean -dfx services
100+
101+
MODEL_FILENAME=${aws_model_file##*/} # Extract the filename from the path
102+
SERVICE_NAME=$(echo "$MODEL_FILENAME" | cut -d. -f1 ) # Extract the service name from the filename
103+
excluded=$(echo "${excluded_services[@]}" | grep -ow "$SERVICE_NAME" | wc -w)
104+
if [[ $excluded == 0 ]]; then
105+
echo "Building docs for $SERVICE_NAME"
106+
107+
./gradlew -Paws.services=+$SERVICE_NAME :codegen:sdk:bootstrap # generate SDK
108+
109+
# Retry due to transient network failures during doc generation
110+
# https://unix.stackexchange.com/a/82602
111+
n=0
112+
until [ "$n" -ge 5 ]
113+
do
114+
./gradlew --no-parallel -PdokkaOutSubDir=$SERVICE_NAME -PsmithyKotlinPackageListUrl=file://$smithy_kotlin_package_list_path dokkaHtmlMultiModule && break
115+
n=$((n+1))
116+
sleep 15
117+
done
118+
119+
docs_generated=true
120+
else # SDK was excluded
121+
echo "Ignoring excluded service $SERVICE_NAME"
122+
fi
123+
done
124+
echo ::set-output name=docs-generated::"$docs_generated"
125+
- name: Compress Docs
126+
if: steps.gen-docs.outputs.docs-generated == 'true'
127+
run: |
128+
tar cJf api-docs-${{ matrix.service-prefix }}.tar.xz build/dokka/*
129+
- name: Upload Artifact
130+
if: steps.gen-docs.outputs.docs-generated == 'true'
131+
uses: actions/upload-artifact@v2
132+
with:
133+
name: api-docs-${{ matrix.service-prefix }}
134+
path: api-docs-${{ matrix.service-prefix }}.tar.xz
135+
retention-days: 1 # These intra-workflow artifacts are not needed after final docs generated
136+
137+
# Download all artifacts from previous job, extract them to common dir, add top-level index and publish docs as release artifact
138+
combine-docs:
139+
needs: [ smithy-kotlin-docs, api-doc-gen-parallel ]
140+
runs-on: ubuntu-latest
141+
steps:
142+
- name: Download all workflow run artifacts
143+
uses: actions/download-artifact@v2
144+
- name: Consolidate Service Docs
145+
run: |
146+
mkdir target
147+
148+
for suffix in {a..z}
149+
do
150+
ARCHIVE="api-docs-$suffix/api-docs-$suffix.tar.xz"
151+
152+
if [ -f "$ARCHIVE" ]; then
153+
tar xf "$ARCHIVE"
154+
mv build/dokka/* target/
155+
rm -Rf build
156+
else
157+
echo "Did not find archive for $ARCHIVE"
158+
fi
159+
done
160+
- name: Add smithy-kotlin docs
161+
run: |
162+
mv smithy-kotlin-docs target/
163+
- name: Generate Top Level Index
164+
run: |
165+
INDEX_FILE=target/index.html
166+
167+
# Generate page header
168+
echo "<!DOCTYPE html>" >> $INDEX_FILE
169+
echo "<html>" >> $INDEX_FILE
170+
echo "" >> $INDEX_FILE
171+
echo "<head>" >> $INDEX_FILE
172+
echo " <meta name='viewport' content='width=device-width, initial-scale=1' charset='UTF-8'>" >> $INDEX_FILE
173+
echo " <title>AWS Services</title>" >> $INDEX_FILE
174+
echo " <link href='images/logo-icon.svg' rel='icon' type='image/svg'>" >> $INDEX_FILE
175+
echo " <link href='styles/style.css' rel='Stylesheet'>" >> $INDEX_FILE
176+
echo " <link href='styles/logo-styles.css' rel='Stylesheet'>" >> $INDEX_FILE
177+
echo " <link href='styles/jetbrains-mono.css' rel='Stylesheet'>" >> $INDEX_FILE
178+
echo " <link href='styles/main.css' rel='Stylesheet'>" >> $INDEX_FILE
179+
echo " <link href='images/logo-icon.svg'>" >> $INDEX_FILE
180+
echo " <link href='images/aws_logo_white_59x35.png'>" >> $INDEX_FILE
181+
echo " <link href='styles/logo-styles.css' rel='Stylesheet'>" >> $INDEX_FILE
182+
echo " <link href='styles/multimodule.css' rel='Stylesheet'>" >> $INDEX_FILE
183+
echo "</head>" >> $INDEX_FILE
184+
echo "" >> $INDEX_FILE
185+
echo "<body>" >> $INDEX_FILE
186+
echo " <div id='container'>" >> $INDEX_FILE
187+
echo " <div id='leftColumn'>" >> $INDEX_FILE
188+
echo " <div id='logo'></div>" >> $INDEX_FILE
189+
echo " </div>" >> $INDEX_FILE
190+
echo " <div id='main' class='main-content'>" >> $INDEX_FILE
191+
echo " <h2>AWS SDK for Kotlin API Docs</h2>" >> $INDEX_FILE
192+
echo " <div class='table'>" >> $INDEX_FILE
193+
194+
# Generate list of services
195+
for aws_service_dir in target/*
196+
do
197+
if [[ "$aws_service_dir" != "target/index.html" && "$aws_service_dir" != "target/smithy-kotlin-docs" ]]; then # no self reference
198+
SERVICE_NAME=${aws_service_dir##*/} # Extract the filename from the path
199+
200+
echo " <div class='table-row'>" >> $INDEX_FILE
201+
echo " <div class='main-subrow '>" >> $INDEX_FILE
202+
echo " <div class='w-100'>" >> $INDEX_FILE
203+
echo " <span class='inline-flex'>" >> $INDEX_FILE
204+
echo " <a href='$SERVICE_NAME/index.html'>$SERVICE_NAME</a>" >> $INDEX_FILE
205+
echo " </span>" >> $INDEX_FILE
206+
echo " </div>" >> $INDEX_FILE
207+
echo " </div>" >> $INDEX_FILE
208+
echo " </div>" >> $INDEX_FILE
209+
210+
fi
211+
done
212+
213+
# Generate page footer
214+
echo " </div>" >> $INDEX_FILE
215+
echo " </div>" >> $INDEX_FILE
216+
echo "</body>" >> $INDEX_FILE
217+
echo "</html>" >> $INDEX_FILE
218+
- name: Copy Styles to root # Take the styles and images from a service into the root for consistent styling
219+
run: |
220+
FIRST_SERVICE=$(find target/ -maxdepth 1 -mindepth 1 -type d | head -n 1)
221+
cp -r $FIRST_SERVICE/styles $FIRST_SERVICE/images target/
222+
- name: Prepare Release
223+
id: prep-release
224+
run: |
225+
mv target kotlin-sdk-api-docs
226+
zip -r kotlin-sdk-api-docs.zip kotlin-sdk-api-docs/
227+
- name: Release
228+
uses: softprops/action-gh-release@v1
229+
with:
230+
tag_name: ${{ needs.smithy-kotlin-docs.outputs.source-ref }}
231+
files: |
232+
kotlin-sdk-api-docs.zip

‎build.gradle.kts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,13 @@ subprojects {
4949
}
5050
}
5151

52+
val smithyKotlinPackageListUrl: String by project
53+
val smithyKotlinDocBaseUrl: String by project
5254
// Configure Dokka to link to smithy-kotlin types
5355
dokkaSourceSets.configureEach {
5456
externalDocumentationLink {
55-
packageListUrl.set(URL("https://raw.githubusercontent.com/awslabs/smithy-kotlin/api-docs/package-list"))
56-
url.set(URL("https://awslabs.github.io/smithy-kotlin/runtime/"))
57+
packageListUrl.set(URL(smithyKotlinPackageListUrl))
58+
url.set(URL(smithyKotlinDocBaseUrl))
5759
}
5860
}
5961
}

‎gradle.properties‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,7 @@ mockkVersion=1.12.0
3939

4040
# logging - JVM
4141
slf4jVersion=1.7.30
42+
43+
# dokka config
44+
smithyKotlinPackageListUrl=
45+
smithyKotlinDocBaseUrl=https://docs.aws.amazon.com/sdk-for-kotlin/latest/reference/smithy-kotlin-docs

0 commit comments

Comments
 (0)