Skip to content

Commit bbbfe2e

Browse files
stocaarostocaaro
authored
chore: Setup typedoc to build references.json and configure release workflow to update docs site (aws-amplify#14255)
* chore: Configure typedoc * Update config * Update workflow to make docs PRs * Empty change * Chop testing short * Remove npm publish things * Add gh var config * Allow empty docs updates * Rewet back to the working change after some testing * Separate out typdoc reference json generation
1 parent cde36a7 commit bbbfe2e

File tree

5 files changed

+119
-0
lines changed

5 files changed

+119
-0
lines changed

‎.github/workflows/callable-docs-update.yml

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Build the API References and open a docs PR
2+
3+
on: workflow_call
4+
5+
jobs:
6+
docs-update-prep:
7+
name: Prepare for docs update
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: Generate a temporary branch name for docs update PR
11+
id: generate-branch-name
12+
run: |
13+
echo "BRANCH_NAME=temp/amplify-js-$(date +%s)" >> "$GITHUB_OUTPUT"
14+
outputs:
15+
branch_name: ${{ steps.generate-branch-name.outputs.BRANCH_NAME }}
16+
17+
docs-update:
18+
name: Publish to amplify-js docs updates
19+
runs-on: ubuntu-latest
20+
needs: docs-update-prep
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
24+
with:
25+
path: amplify-js
26+
# Minimal depth 0 so we can fetch all git tags.
27+
fetch-depth: 0
28+
- name: Checkout staging repo
29+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
30+
with:
31+
repository: ${{ github.repository_owner }}/docs
32+
path: docs
33+
token: ${{ secrets.GH_TOKEN_AMPLIFY_JS_WRITE }}
34+
35+
- name: Setup node and build the repository
36+
uses: ./amplify-js/.github/actions/node-and-build
37+
38+
- name: Set github commit user
39+
env:
40+
GITHUB_EMAIL: ${{ vars.GH_EMAIL }}
41+
GITHUB_USER: ${{ vars.GH_USER }}
42+
run: |
43+
git config --global user.email $GITHUB_EMAIL
44+
git config --global user.name $GITHUB_USER
45+
46+
- name: Build docs references
47+
working-directory: ./amplify-js
48+
run: |
49+
yarn run docs:references
50+
51+
- name: Update API references in the docs site
52+
working-directory: ./docs
53+
run: |
54+
yarn clean-references -- -p amplify-js
55+
git add .
56+
git commit --allow-empty -m "chore: Update amplify-js API references"
57+
58+
- name: Create a docs PR to merge api references back into the docs site
59+
working-directory: ./docs
60+
env:
61+
TEMP_BRANCH_NAME: ${{ needs.docs-update-prep.outputs.branch_name }}
62+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN_AMPLIFY_JS_WRITE }}
63+
run: |
64+
git checkout -b $TEMP_BRANCH_NAME
65+
git push origin $TEMP_BRANCH_NAME
66+
gh pr create -B main -H $TEMP_BRANCH_NAME --title 'chore: amplify-js api references update' --body 'Merge the api references changes from the most recent release.'

‎.github/workflows/push-latest-release.yml

+5
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,8 @@ jobs:
1818
contents: write
1919
secrets: inherit
2020
uses: ./.github/workflows/callable-npm-publish-release.yml
21+
publish-docs:
22+
needs:
23+
- release
24+
secrets: inherit
25+
uses: ./.github/workflows/callable-docs-update.yml

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ packages/**/cypress/videos/
1818
package-lock.json
1919
packages/*/.watchmanconfig
2020
dual-publish-tmp
21+
docs/reference.json
2122

2223
### Version file - core build artifact
2324
packages/core/src/Platform/version.ts

‎package.json

+1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
"test:github-actions": "node ./scripts/test-github-actions.js",
1616
"test:tsc-compliance": "yarn workspace tsc-compliance-test test:compliance",
1717
"docs": "typedoc",
18+
"docs:references": "typedoc --options typedoc.references.json",
1819
"build": "lerna run build --stream && yarn test:duplicates",
1920
"build:watch": "concurrently 'lerna run build:watch --parallel' --raw",
2021
"build:client-types": "cd scripts/dts-bundler && yarn && yarn run build",

‎typedoc.references.json

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"name": "Amplify JS API Documentation",
3+
"entryPointStrategy": "packages",
4+
"entryPoints": [
5+
"packages/adapter-nextjs",
6+
"packages/adapter-nextjs/data",
7+
"packages/aws-amplify",
8+
"packages/aws-amplify/analytics",
9+
"packages/aws-amplify/analytics/kinesis",
10+
"packages/aws-amplify/analytics/kinesis-firehose",
11+
"packages/aws-amplify/analytics/personalize",
12+
"packages/aws-amplify/api",
13+
"packages/aws-amplify/api/server",
14+
"packages/aws-amplify/auth",
15+
"packages/aws-amplify/auth/cognito",
16+
"packages/aws-amplify/auth/server",
17+
"packages/aws-amplify/data",
18+
"packages/aws-amplify/data/server",
19+
"packages/aws-amplify/in-app-messaging",
20+
"packages/aws-amplify/storage",
21+
"packages/aws-amplify/storage/server",
22+
"packages/aws-amplify/utils",
23+
"packages/geo",
24+
"packages/interactions",
25+
"packages/predictions",
26+
"packages/pubsub",
27+
"packages/datastore-storage-adapter"
28+
],
29+
"out": "docs/api",
30+
"json": "docs/reference.json",
31+
"readme": "docs/README.md",
32+
"sortEntryPoints": false,
33+
"includeVersion": false,
34+
"hideGenerator": true,
35+
"navigationLinks": {
36+
"Library Documentation": "https://docs.amplify.aws/",
37+
"NPM": "https://www.npmjs.com/package/aws-amplify",
38+
"GitHub": "https://github.com/aws-amplify/amplify-js"
39+
},
40+
"customCss": "./docs/theme/styles.css",
41+
"favicon": "./docs/theme/favicon.ico",
42+
"plugin": [
43+
"typedoc-plugin-missing-exports",
44+
"typedoc-plugin-extras"
45+
]
46+
}

0 commit comments

Comments
 (0)