From 50921193333fbc246f104df20b2cb3ea871ffaca Mon Sep 17 00:00:00 2001 From: kozub Date: Tue, 18 Jul 2023 15:17:33 +0200 Subject: [PATCH 1/3] docs: add support for docs versioning (#1239) --- .github/workflows/build-docs.yml | 37 ------ .github/workflows/docs.yml | 41 ------- .github/workflows/on-doc-merge.yml | 21 ++++ .github/workflows/rebuild-latest-docs.yml | 39 ++++++ .github/workflows/reusable-publish-docs.yml | 126 ++++++++++++++++++++ mkdocs.yml | 3 + 6 files changed, 189 insertions(+), 78 deletions(-) delete mode 100644 .github/workflows/build-docs.yml delete mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/on-doc-merge.yml create mode 100644 .github/workflows/rebuild-latest-docs.yml create mode 100644 .github/workflows/reusable-publish-docs.yml diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml deleted file mode 100644 index cbcdcdd9e..000000000 --- a/.github/workflows/build-docs.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Build Docs - -on: - pull_request: - branches: - - main - paths: - - 'docs/**' - - 'mkdocs.yml' - - 'Makefile' - - push: - branches: - - main - paths: - - 'docs/**' - - 'mkdocs.yml' - - 'Makefile' - -jobs: - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: "3.8" - - name: Capture branch and tag - id: branch_name - run: | - echo "SOURCE_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV - echo "SOURCE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV - - name: Build docs website - run: | - echo "GIT_PYTHON_REFRESH=quiet" - make build-docs-website \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 9c09e294d..000000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Docs - -on: - release: - types: - - published - workflow_dispatch: {} - -permissions: - id-token: write - contents: write - pages: write - -jobs: - docs: - runs-on: ubuntu-latest - environment: Docs - steps: - - uses: actions/checkout@v3 - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: "3.8" - - name: Capture branch and tag - id: branch_name - run: | - echo "SOURCE_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV - echo "SOURCE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV - - name: Build docs website - run: | - make build-docs-website - - name: Configure AWS credentials - uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef - with: - aws-region: us-east-1 - role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }} - - name: Deploy Docs - run: | - aws s3 sync \ - dist \ - s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/ diff --git a/.github/workflows/on-doc-merge.yml b/.github/workflows/on-doc-merge.yml new file mode 100644 index 000000000..2cea171dc --- /dev/null +++ b/.github/workflows/on-doc-merge.yml @@ -0,0 +1,21 @@ +name: Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "mkdocs.yml" + +jobs: + release-docs: + permissions: + contents: write + pages: write + id-token: write + secrets: inherit + uses: ./.github/workflows/reusable-publish-docs.yml + with: + version: main + alias: stage \ No newline at end of file diff --git a/.github/workflows/rebuild-latest-docs.yml b/.github/workflows/rebuild-latest-docs.yml new file mode 100644 index 000000000..853aaa1d3 --- /dev/null +++ b/.github/workflows/rebuild-latest-docs.yml @@ -0,0 +1,39 @@ +name: Rebuild latest docs + +# PROCESS +# +# 1. Build User Guide and API docs +# 2. Publish to GitHub Pages +# 3. Publish to S3 (new home) + +# USAGE +# +# Only used for deploying a documentation hotfix to /latest and its associated version w/o a full release. +# +# Steps: +# +# 1. Trigger "Rebuild latest docs" workflow manually: https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow +# 2. Use the latest version released under Releases e.g. 2.0.0 + +on: + workflow_dispatch: + inputs: + latest_published_version: + description: "Latest published version to rebuild latest docs for, e.g. 1.4.2" + default: "1.4.2" + required: true + +permissions: + contents: read + +jobs: + release-docs: + permissions: + contents: write # push to gh-pages + pages: write # deploy gh-pages website + id-token: write # trade JWT token for AWS credentials in AWS Docs account + secrets: inherit + uses: ./.github/workflows/reusable_publish_docs.yml + with: + version: ${{ inputs.latest_published_version }} + alias: latest diff --git a/.github/workflows/reusable-publish-docs.yml b/.github/workflows/reusable-publish-docs.yml new file mode 100644 index 000000000..71c84392a --- /dev/null +++ b/.github/workflows/reusable-publish-docs.yml @@ -0,0 +1,126 @@ +name: Reusable Publish docs + +env: + BRANCH: main + ORIGIN: aws-powertools/powertools-lambda-java + VERSION: "" + +on: + workflow_call: + inputs: + version: + description: "Version to build and publish docs (1.28.0, develop)" + required: true + type: string + alias: + description: "Alias to associate version (latest, stage)" + required: true + type: string + detached_mode: + description: "Whether it's running in git detached mode to ensure git is sync'd" + required: false + default: false + type: boolean + +permissions: + contents: write + id-token: write + pages: write + +jobs: + publish-docs: + runs-on: ubuntu-latest + environment: Docs + steps: + - name: Checkout code + uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2 + with: + # While `fetch-depth` is used to allow the workflow to later commit & push the changes. + fetch-depth: 0 + - name: Setup dependencies + uses: ./.github/actions/cached-node-modules + - name: Set up Python + uses: actions/setup-python@57ded4d7d5e986d7296eab16560982c6dd7c923b # v4.6.0 + with: + python-version: "3.8" + - name: Install doc generation dependencies + run: | + pip install --upgrade pip + pip install -r docs/requirements.txt + - name: Setup doc deploy + run: | + git config --global user.name Docs deploy + git config --global user.email aws-devax-open-source@amazon.com + - name: Git refresh tip (detached mode) + # Git Detached mode (release notes) doesn't have origin + if: ${{ inputs.detached_mode }} + run: | + git config pull.rebase true + git config remote.origin.url >&- || git remote add origin https://github.com/"$ORIGIN" + git pull origin "$BRANCH" + - name: Normalize Version Number + run: echo "VERSION=$(echo ${{ inputs.version }} | sed 's/v//')" >> $GITHUB_ENV + - name: Build docs website and API reference + env: + ALIAS: ${{ inputs.alias }} + run: | + rm -rf site + mkdocs build + mike deploy --update-aliases --no-redirect ${{ env.VERSION }} ${{ env.ALIAS }} --branch backup-gh-pages + # Set latest version as a default + mike set-default latest --branch backup-gh-pages + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef # v2.0.0 + with: + aws-region: us-east-1 + role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }} + - name: Copy API Docs + run: | + cp -r api site/ + +## Uncomment to deploy to s3 +# - name: Deploy Docs (Version) +# env: +# VERSION: ${{ inputs.version }} +# ALIAS: ${{ inputs.alias }} +# run: | +# aws s3 sync \ +# site/ \ +# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/ +# - name: Deploy Docs (Alias) +# env: +# VERSION: ${{ inputs.version }} +# ALIAS: ${{ inputs.alias }} +# run: | +# aws s3 sync \ +# site/ \ +# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/ +# - name: Deploy Docs (Version JSON) +# env: +# VERSION: ${{ inputs.version }} +# ALIAS: ${{ inputs.alias }} + + + # We originally used "mike" from PyPi to manage versions for us, but since we moved to S3, we can't use it to manage versions any more. + # Instead, we're using some shell script that manages the versions. + # + # Operations: + # 1. Download the versions.json file from S3 + # 2. Find any reference to the alias and delete it from the versions file + # 3. This is voodoo (don't use JQ): + # - we assign the input as $o and the new version/alias as $n, + # - we check if the version number exists in the file already (for republishing docs) + # - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input) + # - if it's a new version number, we add it at position 0 in the array. + # 4. Once done, we'll upload it back to S3. + +## Uncomment to deploy to s3 +# run: | +# aws s3 cp \ +# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \ +# versions_old.json +# jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json +# jq '. as $o | [{"title": "${{ env.VERSION }}", "version": "${{ env.VERSION }}", "aliases": ["${{env.ALIAS}}"] }] as $n | $n | if .[0].title | test("[a-z]+") or any($o[].title == "${{ env.VERSION }}";.) then $o else $n + $o end' < versions_proc.json > versions.json +# aws s3 cp \ +# versions.json \ +# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json diff --git a/mkdocs.yml b/mkdocs.yml index 5fd3206b0..5c7f562c1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,6 +82,9 @@ extra_javascript: - javascript/extra.js extra: + version: + provider: mike + default: latest powertools: version: 1.16.0 # to update after each release (we do not want snapshot version here) From 85200beadfbd9de87dc47d269330c74e4594ec4e Mon Sep 17 00:00:00 2001 From: kozub Date: Fri, 21 Jul 2023 13:09:30 +0200 Subject: [PATCH 2/3] docs: change configuration to release docs only during the release or by hand. Rollback config for building doc for PR. (#1239) --- .github/workflows/build-docs.yml | 37 +++++++++++++++++++ .../{on-doc-merge.yml => release-doc.yml} | 10 ++--- 2 files changed, 41 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/build-docs.yml rename .github/workflows/{on-doc-merge.yml => release-doc.yml} (74%) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 000000000..15d08587d --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,37 @@ +name: Build Docs + +on: + pull_request: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'Makefile' + + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'Makefile' + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.8" + - name: Capture branch and tag + id: branch_name + run: | + echo "SOURCE_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV + echo "SOURCE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV + - name: Build docs website + run: | + echo "GIT_PYTHON_REFRESH=quiet" + make build-docs-website diff --git a/.github/workflows/on-doc-merge.yml b/.github/workflows/release-doc.yml similarity index 74% rename from .github/workflows/on-doc-merge.yml rename to .github/workflows/release-doc.yml index 2cea171dc..5f87f970a 100644 --- a/.github/workflows/on-doc-merge.yml +++ b/.github/workflows/release-doc.yml @@ -1,12 +1,10 @@ name: Docs on: - push: - branches: - - main - paths: - - "docs/**" - - "mkdocs.yml" + release: + types: + - published + workflow_dispatch: {} jobs: release-docs: From a9e9ee54c9924452a625f0113356b0a0bbf278dc Mon Sep 17 00:00:00 2001 From: kozub Date: Fri, 28 Jul 2023 08:38:11 +0200 Subject: [PATCH 3/3] docs: Uncomment logic responsible for pushing changes to S3.(#1239) --- .github/workflows/reusable-publish-docs.yml | 60 ++++++++++----------- 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/.github/workflows/reusable-publish-docs.yml b/.github/workflows/reusable-publish-docs.yml index 71c84392a..9ab53dac2 100644 --- a/.github/workflows/reusable-publish-docs.yml +++ b/.github/workflows/reusable-publish-docs.yml @@ -78,27 +78,26 @@ jobs: run: | cp -r api site/ -## Uncomment to deploy to s3 -# - name: Deploy Docs (Version) -# env: -# VERSION: ${{ inputs.version }} -# ALIAS: ${{ inputs.alias }} -# run: | -# aws s3 sync \ -# site/ \ -# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/ -# - name: Deploy Docs (Alias) -# env: -# VERSION: ${{ inputs.version }} -# ALIAS: ${{ inputs.alias }} -# run: | -# aws s3 sync \ -# site/ \ -# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/ -# - name: Deploy Docs (Version JSON) -# env: -# VERSION: ${{ inputs.version }} -# ALIAS: ${{ inputs.alias }} + - name: Deploy Docs (Version) + env: + VERSION: ${{ inputs.version }} + ALIAS: ${{ inputs.alias }} + run: | + aws s3 sync \ + site/ \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/ + - name: Deploy Docs (Alias) + env: + VERSION: ${{ inputs.version }} + ALIAS: ${{ inputs.alias }} + run: | + aws s3 sync \ + site/ \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/ + - name: Deploy Docs (Version JSON) + env: + VERSION: ${{ inputs.version }} + ALIAS: ${{ inputs.alias }} # We originally used "mike" from PyPi to manage versions for us, but since we moved to S3, we can't use it to manage versions any more. @@ -114,13 +113,12 @@ jobs: # - if it's a new version number, we add it at position 0 in the array. # 4. Once done, we'll upload it back to S3. -## Uncomment to deploy to s3 -# run: | -# aws s3 cp \ -# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \ -# versions_old.json -# jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json -# jq '. as $o | [{"title": "${{ env.VERSION }}", "version": "${{ env.VERSION }}", "aliases": ["${{env.ALIAS}}"] }] as $n | $n | if .[0].title | test("[a-z]+") or any($o[].title == "${{ env.VERSION }}";.) then $o else $n + $o end' < versions_proc.json > versions.json -# aws s3 cp \ -# versions.json \ -# s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json + run: | + aws s3 cp \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \ + versions_old.json + jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json + jq '. as $o | [{"title": "${{ env.VERSION }}", "version": "${{ env.VERSION }}", "aliases": ["${{env.ALIAS}}"] }] as $n | $n | if .[0].title | test("[a-z]+") or any($o[].title == "${{ env.VERSION }}";.) then $o else $n + $o end' < versions_proc.json > versions.json + aws s3 cp \ + versions.json \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json