ci: Overhaul docs and deploy

.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
+      - 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
   #
-#    # Only run this when pushing to master branch
-#    if: github.ref == 'refs/heads/master'
-#    steps:
-#      - uses: actions/checkout@v3
+  # 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 
   #
-#      - 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
+  # 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
   #