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