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: cargo xtask book
-        run: cd book/en && if mdbook build |& tee /dev/tty | grep "\[ERROR\]"; then exit 1; else exit 0; fi
 
       - 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
+      - name: Archive the book + API docs
-#  #
+        run: |
-#  # This needs to run before book is built
+          cp -r $td bookroot
-#  mergetostablebranch:
+          tar -cf book.tar bookroot
-#    name: If CI passes, merge master branch into release/vX
+
-#    runs-on: ubuntu-22.04
+      - name: Store the Book + API docs
-#    needs:
+        uses: actions/upload-artifact@v3
-#      - style
+        with:
-#      - check
+          name: book
-#      - clippy
+          path: book.tar
-#      - checkexamples
+
-#      - testexamples
+  mdbookold:
-#      - checkmacros
+    name: build docs and mdbook for older releases
-#      - testmacros
+    runs-on: ubuntu-22.04
-#      - tests
+    steps:
-#      - docs
+      - name: Checkout
-#      - mdbook
+        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
+  # This is only valid when current stable resides in
-#    if: github.ref == 'refs/heads/master'
+  # master branch.
-#    steps:
+  # As master moves on to development, the work on the
-#      - uses: actions/checkout@v3
+  # 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
+  # This needs to run before book is built, as bookbuilding fetches from the branch
-#        id: crateversionbranch
+  mergetostablebranch:
-#        # Parse metadata for version number, extract the Semver Major
+    name: If CI passes, merge master branch into release/vX
-#        run: |
+    runs-on: ubuntu-22.04
-#          VERSION=$(cargo metadata --format-version 1 --no-deps --offline | jq -r '.packages[] | select(.name =="cortex-m-rtic") | .version')
+    needs:
-#          VERSIONMAJOR=${VERSION%.*.*}
+      - parseversion
-#          echo "branch=release/v$VERSIONMAJOR" >> $GITHUB_ENV
+      - formatcheck
-#          echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV
+      - check
-#          echo "version=$VERSION" >> $GITHUB_ENV
+      - clippy
-#
+      - checkexamples
-#      - uses: everlytic/branch-merge@1.1.5
+      - testexamples
-#        with:
+      - tests
-#          github_token: ${{ github.token }}
+      - docs
-#          source_ref: 'master'
+      - mdbook
-#          target_branch: ${{ env.branch }}
+
-#          commit_message_template: '[Bors] Merged {source_ref} into target {target_branch}'
+    # Only run this when pushing to master branch
-#
+    if: github.ref == 'refs/heads/master'
-#  # Only runs when pushing to master branch
+    steps:
-#  # Bors run CI against staging branch,
+      - uses: actions/checkout@v3
-#  # if that succeeds Borst tries against master branch
+
-#  # If all tests pass, then deploy stage is run
+      - name: Push to stable release branch if master contains stable version
-#  deploy:
+        if: ${{ env.versionmajor == env.STABLE_VERSION }}
-#    name: deploy
+        run: git push -u origin ${{ env.branch }}
-#    runs-on: ubuntu-22.04
+
-#    needs:
+  # Only runs when pushing to master branch
-#      mergetostablebranch
+  # Bors run CI against staging branch,
-#      docs      
+  # if that succeeds Borst tries against master branch
-#      mdbook
+  # If all tests pass, then deploy stage is run
-#
+  deploy:
-#    # Only run this when pushing to master branch
+    name: deploy
-#    if: github.ref == 'refs/heads/master'
+    runs-on: ubuntu-22.04
-#    steps:
+    needs:
-#      - uses: actions/checkout@v3
+      - parseversion
-#
+      - mergetostablebranch
-#     - name: Install lychee
+      - docs      
-#       uses: taiki-e/install-action@v2
+      - mdbookold      
-#       with:
+      - mdbook
-#         tool: lychee
+
-#
+    # Only run this when pushing to master branch
-#      - name: Install mdbook-mermaid
+    if: github.ref == 'refs/heads/master'
-#        uses: taiki-e/install-action@v2
+    steps:
-#        with:
+      - uses: actions/checkout@v3
-#          tool: mdbook-mermaid
+
-# 
+      - name: Install lychee
-#      - name: mdBook Action
+        uses: taiki-e/install-action@v2
-#        uses: peaceiris/actions-mdbook@v1
+        with:
-#        with:
+         tool: lychee
-#          mdbook-version: 'latest'
+
-#
+      - name: Install mdbook-mermaid
-#      - name: Get crate version
+        uses: taiki-e/install-action@v2
-#        id: crateversion
+        with:
-#        # Parse metadata for version number, extract the Semver Major
+          tool: mdbook-mermaid
-#        run: |
+ 
-#          VERSION=$(cargo metadata --format-version 1 --no-deps --offline | jq -r '.packages[] | select(.name =="cortex-m-rtic") | .version')
+      - name: mdBook Action
-#          VERSIONMAJOR=${VERSION%.*.*}
+        uses: peaceiris/actions-mdbook@v1
-#          echo "branch=release/v$VERSIONMAJOR" >> $GITHUB_ENV
+        with:
-#          echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV
+          mdbook-version: 'latest'
-#          echo "version=$VERSION" >> $GITHUB_ENV
+
-#
+      - name: Remove cargo-config
-#      - name: Remove cargo-config
+        run: rm -f .cargo/config
-#        run: rm -f .cargo/config
+
-#
+      - name: Download built dev-ver book and API docs
-#      # TODO: Download API docs artifacts instead
+        uses: actions/download-artifact@v3
-#      - name: Build docs
+        with:
-#        run: cargo doc
+          name: book
-#
+
-#      - name: Build books
+      - name: Extract the dev-version book and API docs
-#        shell: 'script --return --quiet --command "bash {0}"'
+        run: |
-#        run: |
+          tar -xf book.tar 
-#          langs=( en )
+
-#          devver=( dev )
+      - name: Download built old versions of books and API docs
-#          # The latest stable must be the first element in the array
+        uses: actions/download-artifact@v3
-#          vers=( "1" "0.5" "0.4"  )
+        with:
-#
+          name: mdbookold
-#          # All releases start with "v"
+
-#          # followed by MAJOR.MINOR.PATCH, see semver.org
+      - name: Extract the old version books and API docs
-#          # Store first in array as stable
+        run: |
-#          stable=${vers}
+          tar -xf mdbookold.tar 
-#          crateversion={{ env.versionmajor }}
+
-#
+      - name: Prepare books
-#          echo "Latest stable version: $stable"
+        shell: 'script --return --quiet --command "bash {0}"'
-#          echo "Current crate version: $crateversion"
+        run: |
-#
+          langs=( en )
-#          # Create directories
+          devver=( dev )
-#          td=$(mktemp -d)
+          # The latest stable must be the first element in the array
-#          mkdir -p $td/$devver/book/
+          vers=( "${{ env.STABLE_VERSION }}" "${{ env.OLDSTABLE_VERSION }}" )
-#          cp -r target/doc $td/$devver/api
+
-#
+          # All releases start with "v"
-#          # Redirect rtic.rs/meeting/index.html to hackmd
+          # followed by MAJOR.MINOR.PATCH, see semver.org
-#          mkdir $td/meeting
+          # Store first in array as stable
-#          sed "s|URL|https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg|g" redirect.html > $td/meeting/index.html
+          stable=${vers}
-#          sed -i "s|Page Redirection|RTIC Meeting|" $td/meeting/index.html
+          crateversion=${{ env.versionmajor }}
-#          sed -i "s|If you|Redirecting to RTIC HackMD. If you|" $td/meeting/index.html
+
-#
+          echo "Latest stable version: $stable"
-#          # Redirect the main site to the stable release
+          echo "Current crate version: $crateversion"
-#          sed "s|URL|$stable|g" redirect.html > $td/index.html
+
-#
+          # Create directories
-#          # Create the redirects for dev-version
+          td=$(mktemp -d)
-#          # If the current stable and the version being built differ,
+          mkdir -p $td/$devver/
-#          # then there is a dev-version and the links should point to it.
+          cp -r bookroot/* $td/$devver/
-#          if [[ "$stable" != "$crateversion" ]];
+
-#          then
+          # Redirect rtic.rs/meeting/index.html to hackmd
-#            sed 's|URL|rtic/index.html|g' redirect.html > $td/$devver/api/index.html
+          mkdir $td/meeting
-#            sed 's|URL|book/en|g' redirect.html > $td/$devver/index.html
+          sed "s|URL|https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg|g" redirect.html > $td/meeting/index.html
-#          else
+          sed -i "s|Page Redirection|RTIC Meeting|" $td/meeting/index.html
-#            # If the current stable and the "dev" version in master branch
+          sed -i "s|If you|Redirecting to RTIC HackMD. If you|" $td/meeting/index.html
-#            # 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
+          # Redirect the main site to the stable release
-#            sed 's|URL|rtic.rs/$stable|g' redirect.html > $td/$devver/index.html
+          sed "s|URL|$stable|g" redirect.html > $td/index.html
-#          fi
+
-#
+          # Create the redirects for dev-version
-#          # Build books
+          # If the current stable and the version being built differ,
-#          # TODO: Download books artifacts instead
+          # then there is a dev-version and the links should point to it.
-#          for lang in ${langs[@]}; do
+          if [[ "$stable" != "$crateversion" ]];
-#              ( cd book/$lang &&
+          then
-#                if mdbook build |& tee /dev/tty | grep "\[ERROR\]"; then exit 1; else exit 0; fi
+            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
-#              cp -r book/$lang/book $td/$devver/book/$lang
+          else
-#              cp LICENSE-* $td/$devver/book/$lang/
+            # If the current stable and the "dev" version in master branch
-#          done
+            # 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
-#          # Build older versions, including stable
+            sed 's|URL|rtic.rs/$stable/api/rtic|g' redirect.html > $td/$devver/api/index.html
-#          root=$(pwd)
+            sed 's|URL|rtic.rs/$stable|g' redirect.html > $td/$devver/index.html
-#          for ver in ${vers[@]}; do
+          fi
-#              prefix=${ver}
+
-#
+          # Package older versions, including stable
-#              mkdir -p $td/$prefix/book
+
-#              src=$(mktemp -d)
+          # Copy the stable book to the stable alias
-#              curl -L https://github.com/rtic-rs/cortex-m-rtic/archive/release/v${ver}.tar.gz | tar xz --strip-components 1 -C $src
+          cp -r mdbookold/${{ env.STABLE_VERSION }} $td/stable
-#
+
-#              pushd $src
+          # Copy the stable book to the webroot
-#              rm -f .cargo/config
+          cp -r mdbookold/${{ env.STABLE_VERSION }} $td/
-#              cargo doc --features thumbv7-backend || cargo doc --features thumbv7-backend,timer-queue
+          # Copy the old stable book to the webroot
-#              cp -r target/doc $td/$prefix/api
+          cp -r mdbookold/${{ env.OLDSTABLE_VERSION }} $td/
-#              sed 's|URL|rtic/index.html|g' $root/redirect.html > $td/$prefix/api/index.html
+
-#              for lang in ${langs[@]}; do
+          # Forward CNAME file
-#                  ( cd book/$lang &&
+          cp CNAME $td/
-#                    if mdbook build |& tee /dev/tty | grep "\[ERROR\]"; then exit 1; else exit 0; fi
+          mv $td/ bookstodeploy
-#                  )
+
-#                  cp -r book/$lang/book $td/$prefix/book/$lang
+      - name: Deploy to GH-pages
-#                  cp LICENSE-* $td/$prefix/book/$lang/
+        uses: peaceiris/actions-gh-pages@v3
-#              done
+        with:
-#              sed 's|URL|book/en|g' $root/redirect.html > $td/$prefix/index.html
+          github_token: ${{ secrets.GITHUB_TOKEN }}
-#              popd
+          publish_dir: ./bookstodeploy
-#
+          force_orphan: true
-#              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
 
   # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149
   #