From 38a48e5d5cf8f81d53b84cee5a9109c664370fe8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sat, 4 Mar 2023 00:10:08 +0100 Subject: [PATCH] ci: Overhaul docs and deploy --- .github/workflows/build.yml | 436 ++++++++++++++++++++---------------- 1 file changed, 245 insertions(+), 191 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f895b9a0a8..96e1540ead 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,6 +11,10 @@ on: env: CARGO_TERM_COLOR: always + DEV_VERSION: 2 + STABLE_VERSION: 1 + OLDSTABLE_VERSION: 0.5 + OLDOLDSTABLE_VERSION: 0.4 jobs: # Run cargo xtask format-check @@ -304,19 +308,18 @@ jobs: with: tool: lychee + - name: Install mdbook + uses: taiki-e/install-action@v2 + with: + tool: mdbook + - name: Install mdbook-mermaid uses: taiki-e/install-action@v2 with: tool: mdbook-mermaid - - name: mdBook Action - uses: peaceiris/actions-mdbook@v1 - with: - mdbook-version: 'latest' - - name: Build book in English - shell: 'script --return --quiet --command "bash {0}"' - run: cd book/en && if mdbook build |& tee /dev/tty | grep "\[ERROR\]"; then exit 1; else exit 0; fi + run: cargo xtask book - name: Download built API docs uses: actions/download-artifact@v3 @@ -336,190 +339,241 @@ jobs: lychee --offline --format detailed $td/book/en/ -# # Update stable branch -# # -# # This needs to run before book is built -# mergetostablebranch: -# name: If CI passes, merge master branch into release/vX -# runs-on: ubuntu-22.04 -# needs: -# - style -# - check -# - clippy -# - checkexamples -# - testexamples -# - checkmacros -# - testmacros -# - tests -# - docs -# - mdbook -# -# # Only run this when pushing to master branch -# if: github.ref == 'refs/heads/master' -# steps: -# - uses: actions/checkout@v3 -# -# - name: Get crate version and print output branch release/vX -# id: crateversionbranch -# # Parse metadata for version number, extract the Semver Major -# run: | -# VERSION=$(cargo metadata --format-version 1 --no-deps --offline | jq -r '.packages[] | select(.name =="cortex-m-rtic") | .version') -# VERSIONMAJOR=${VERSION%.*.*} -# echo "branch=release/v$VERSIONMAJOR" >> $GITHUB_ENV -# echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV -# echo "version=$VERSION" >> $GITHUB_ENV -# -# - uses: everlytic/branch-merge@1.1.5 -# with: -# github_token: ${{ github.token }} -# source_ref: 'master' -# target_branch: ${{ env.branch }} -# commit_message_template: '[Bors] Merged {source_ref} into target {target_branch}' -# -# # Only runs when pushing to master branch -# # Bors run CI against staging branch, -# # if that succeeds Borst tries against master branch -# # If all tests pass, then deploy stage is run -# deploy: -# name: deploy -# runs-on: ubuntu-22.04 -# needs: -# mergetostablebranch -# docs -# mdbook -# -# # Only run this when pushing to master branch -# if: github.ref == 'refs/heads/master' -# steps: -# - uses: actions/checkout@v3 -# -# - name: Install lychee -# uses: taiki-e/install-action@v2 -# with: -# tool: lychee -# -# - name: Install mdbook-mermaid -# uses: taiki-e/install-action@v2 -# with: -# tool: mdbook-mermaid -# -# - name: mdBook Action -# uses: peaceiris/actions-mdbook@v1 -# with: -# mdbook-version: 'latest' -# -# - name: Get crate version -# id: crateversion -# # Parse metadata for version number, extract the Semver Major -# run: | -# VERSION=$(cargo metadata --format-version 1 --no-deps --offline | jq -r '.packages[] | select(.name =="cortex-m-rtic") | .version') -# VERSIONMAJOR=${VERSION%.*.*} -# echo "branch=release/v$VERSIONMAJOR" >> $GITHUB_ENV -# echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV -# echo "version=$VERSION" >> $GITHUB_ENV -# -# - name: Remove cargo-config -# run: rm -f .cargo/config -# -# # TODO: Download API docs artifacts instead -# - name: Build docs -# run: cargo doc -# -# - name: Build books -# shell: 'script --return --quiet --command "bash {0}"' -# run: | -# langs=( en ) -# devver=( dev ) -# # The latest stable must be the first element in the array -# vers=( "1" "0.5" "0.4" ) -# -# # All releases start with "v" -# # followed by MAJOR.MINOR.PATCH, see semver.org -# # Store first in array as stable -# stable=${vers} -# crateversion={{ env.versionmajor }} -# -# echo "Latest stable version: $stable" -# echo "Current crate version: $crateversion" -# -# # Create directories -# td=$(mktemp -d) -# mkdir -p $td/$devver/book/ -# cp -r target/doc $td/$devver/api -# -# # Redirect rtic.rs/meeting/index.html to hackmd -# mkdir $td/meeting -# sed "s|URL|https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg|g" redirect.html > $td/meeting/index.html -# sed -i "s|Page Redirection|RTIC Meeting|" $td/meeting/index.html -# sed -i "s|If you|Redirecting to RTIC HackMD. If you|" $td/meeting/index.html -# -# # Redirect the main site to the stable release -# sed "s|URL|$stable|g" redirect.html > $td/index.html -# -# # Create the redirects for dev-version -# # If the current stable and the version being built differ, -# # then there is a dev-version and the links should point to it. -# if [[ "$stable" != "$crateversion" ]]; -# then -# sed 's|URL|rtic/index.html|g' redirect.html > $td/$devver/api/index.html -# sed 's|URL|book/en|g' redirect.html > $td/$devver/index.html -# else -# # If the current stable and the "dev" version in master branch -# # share the same major version, redirect dev/ to stable book -# sed 's|URL|rtic.rs/$stable/api/rtic|g' redirect.html > $td/$devver/api/index.html -# sed 's|URL|rtic.rs/$stable|g' redirect.html > $td/$devver/index.html -# fi -# -# # Build books -# # TODO: Download books artifacts instead -# for lang in ${langs[@]}; do -# ( cd book/$lang && -# if mdbook build |& tee /dev/tty | grep "\[ERROR\]"; then exit 1; else exit 0; fi -# ) -# cp -r book/$lang/book $td/$devver/book/$lang -# cp LICENSE-* $td/$devver/book/$lang/ -# done -# -# # Build older versions, including stable -# root=$(pwd) -# for ver in ${vers[@]}; do -# prefix=${ver} -# -# mkdir -p $td/$prefix/book -# src=$(mktemp -d) -# curl -L https://github.com/rtic-rs/cortex-m-rtic/archive/release/v${ver}.tar.gz | tar xz --strip-components 1 -C $src -# -# pushd $src -# rm -f .cargo/config -# cargo doc --features thumbv7-backend || cargo doc --features thumbv7-backend,timer-queue -# cp -r target/doc $td/$prefix/api -# sed 's|URL|rtic/index.html|g' $root/redirect.html > $td/$prefix/api/index.html -# for lang in ${langs[@]}; do -# ( cd book/$lang && -# if mdbook build |& tee /dev/tty | grep "\[ERROR\]"; then exit 1; else exit 0; fi -# ) -# cp -r book/$lang/book $td/$prefix/book/$lang -# cp LICENSE-* $td/$prefix/book/$lang/ -# done -# sed 's|URL|book/en|g' $root/redirect.html > $td/$prefix/index.html -# popd -# -# rm -rf $src -# done -# -# # Copy the stable book to the stable alias -# cp -r $td/$stable $td/stable -# -# # Forward CNAME file -# cp CNAME $td/ -# mv $td/ bookstodeploy -# -# - name: Deploy to GH-pages -# uses: peaceiris/actions-gh-pages@v3 -# with: -# github_token: ${{ secrets.GITHUB_TOKEN }} -# publish_dir: ./bookstodeploy -# force_orphan: true + - name: Archive the book + API docs + run: | + cp -r $td bookroot + tar -cf book.tar bookroot + + - name: Store the Book + API docs + uses: actions/upload-artifact@v3 + with: + name: book + path: book.tar + + mdbookold: + name: build docs and mdbook for older releases + runs-on: ubuntu-22.04 + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Remove cargo-config + run: rm -f .cargo/config + + - name: Prepare output folder + run: mkdir -p mdbookold + + - name: Fetch and build books for older versions + run: | + # The latest stable must be the first element in the array + vers=( "${{ env.STABLE_VERSION }}" "${{ env.OLDSTABLE_VERSION }}" ) + langs=( en ) + root=$(pwd) + webroot=$(pwd)/mdbookold + + for ver in ${vers[@]}; do + + src=$(mktemp -d) + curl -L https://github.com/rtic-rs/rtic/archive/release/v${ver}.tar.gz | tar xz --strip-components 1 -C $src + + pushd $src + rm -f .cargo/config + cargo doc --features thumbv7-backend || cargo doc --features thumbv7-backend,timer-queue + cp -r target/doc $webroot/$ver/api + sed 's|URL|rtic/index.html|g' $webroot/redirect.html > $webroot/$ver/api/index.html + popd + + for lang in ${langs[@]}; do + cargo xtask book build $src/book/$lang + + cp -r book/$lang/$book $webroot/$ver/book/$lang + cp LICENSE-* $webroot/$ver/book/$lang/ + done + sed 's|URL|book/en|g' $webroot/redirect.html > $webroot/$ver/index.html + + rm -rf $src + done + + - name: Archive the old books + run: | + tar -cf mdbookold.tar mdbookold + + - name: Store the old API docs + uses: actions/upload-artifact@v3 + with: + name: mdbookold + path: mdbookold.tar + + parseversion: + # Only run this when pushing to master branch + if: github.ref == 'refs/heads/master' + steps: + - uses: actions/checkout@v3 + + - name: Get crate version and print output branch release/vX + id: crateversionbranch + # Parse metadata for version number, extract the Semver Major + run: | + VERSION=$(cargo metadata --format-version 1 --no-deps --offline | jq -r '.packages[] | select(.name =="rtic") | .version') + VERSIONMAJOR=${VERSION%.*.*} + echo "branch=release/v$VERSIONMAJOR" >> $GITHUB_ENV + echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV + echo "version=$VERSION" >> $GITHUB_ENV + + + # Update stable branch + # + # This is only valid when current stable resides in + # master branch. + # As master moves on to development, the work on the + # stable version will happen in release/v"stable_version". + # Thus, no need to push changes + # + # This needs to run before book is built, as bookbuilding fetches from the branch + mergetostablebranch: + name: If CI passes, merge master branch into release/vX + runs-on: ubuntu-22.04 + needs: + - parseversion + - formatcheck + - check + - clippy + - checkexamples + - testexamples + - tests + - docs + - mdbook + + # Only run this when pushing to master branch + if: github.ref == 'refs/heads/master' + steps: + - uses: actions/checkout@v3 + + - name: Push to stable release branch if master contains stable version + if: ${{ env.versionmajor == env.STABLE_VERSION }} + run: git push -u origin ${{ env.branch }} + + # Only runs when pushing to master branch + # Bors run CI against staging branch, + # if that succeeds Borst tries against master branch + # If all tests pass, then deploy stage is run + deploy: + name: deploy + runs-on: ubuntu-22.04 + needs: + - parseversion + - mergetostablebranch + - docs + - mdbookold + - mdbook + + # Only run this when pushing to master branch + if: github.ref == 'refs/heads/master' + steps: + - uses: actions/checkout@v3 + + - name: Install lychee + uses: taiki-e/install-action@v2 + with: + tool: lychee + + - name: Install mdbook-mermaid + uses: taiki-e/install-action@v2 + with: + tool: mdbook-mermaid + + - name: mdBook Action + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: 'latest' + + - name: Remove cargo-config + run: rm -f .cargo/config + + - name: Download built dev-ver book and API docs + uses: actions/download-artifact@v3 + with: + name: book + + - name: Extract the dev-version book and API docs + run: | + tar -xf book.tar + + - name: Download built old versions of books and API docs + uses: actions/download-artifact@v3 + with: + name: mdbookold + + - name: Extract the old version books and API docs + run: | + tar -xf mdbookold.tar + + - name: Prepare books + shell: 'script --return --quiet --command "bash {0}"' + run: | + langs=( en ) + devver=( dev ) + # The latest stable must be the first element in the array + vers=( "${{ env.STABLE_VERSION }}" "${{ env.OLDSTABLE_VERSION }}" ) + + # All releases start with "v" + # followed by MAJOR.MINOR.PATCH, see semver.org + # Store first in array as stable + stable=${vers} + crateversion=${{ env.versionmajor }} + + echo "Latest stable version: $stable" + echo "Current crate version: $crateversion" + + # Create directories + td=$(mktemp -d) + mkdir -p $td/$devver/ + cp -r bookroot/* $td/$devver/ + + # Redirect rtic.rs/meeting/index.html to hackmd + mkdir $td/meeting + sed "s|URL|https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg|g" redirect.html > $td/meeting/index.html + sed -i "s|Page Redirection|RTIC Meeting|" $td/meeting/index.html + sed -i "s|If you|Redirecting to RTIC HackMD. If you|" $td/meeting/index.html + + # Redirect the main site to the stable release + sed "s|URL|$stable|g" redirect.html > $td/index.html + + # Create the redirects for dev-version + # If the current stable and the version being built differ, + # then there is a dev-version and the links should point to it. + if [[ "$stable" != "$crateversion" ]]; + then + sed 's|URL|rtic/index.html|g' redirect.html > $td/$devver/api/index.html + sed 's|URL|book/en|g' redirect.html > $td/$devver/index.html + else + # If the current stable and the "dev" version in master branch + # share the same major version, redirect dev/ to stable book + # This makes sense, preferable to have doc/book updates going live directly to rtic.rs + sed 's|URL|rtic.rs/$stable/api/rtic|g' redirect.html > $td/$devver/api/index.html + sed 's|URL|rtic.rs/$stable|g' redirect.html > $td/$devver/index.html + fi + + # Package older versions, including stable + + # Copy the stable book to the stable alias + cp -r mdbookold/${{ env.STABLE_VERSION }} $td/stable + + # Copy the stable book to the webroot + cp -r mdbookold/${{ env.STABLE_VERSION }} $td/ + # Copy the old stable book to the webroot + cp -r mdbookold/${{ env.OLDSTABLE_VERSION }} $td/ + + # Forward CNAME file + cp CNAME $td/ + mv $td/ bookstodeploy + + - name: Deploy to GH-pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./bookstodeploy + force_orphan: true # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149 #