Consolidate the book & API building steps

.github/actions/book-prerequisites/action.yml

@@ -0,0 +1,20 @@
+name: Install prerequisites for building the book
+description: "Install mdBook, mdBook-mermaid, and lychee"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install lychee
+      uses: taiki-e/install-action@v2
+      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

.github/workflows/build.yml

@@ -16,6 +16,10 @@ env:
   OLDSTABLE_VERSION: 0.5
   OLDOLDSTABLE_VERSION: 0.4
 
+  OLD_BOOKS_ROOT: old/
+  CURRENT_BOOK_ROOT: current/
+  WEB_ROOT: deploy/
+
 jobs:
   # Run cargo xtask format-check
   formatcheck:
@@ -250,116 +254,54 @@ jobs:
       - name: Run cargo test
         run: cargo xtask --deny-warnings --backend ${{ matrix.backend }} test ${{ matrix.package }}
 
-  # Build documentation, check links
-  docs:
-    name: build docs
+  # Build book for current version, check links
+  current-book:
+    name: Build book for the current version
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Install lychee
-        uses: taiki-e/install-action@v2
-        with:
-          tool: lychee
+      - name: Install book prerequisites
+        uses: ./.github/actions/book-prerequisites
 
+      # Build book & docs for the current version
+      #
+      # This also checks the links for the API docs and
+      # the book using lychee
       - name: Build docs
-        # TODO: Any difference between backends?
-        run: cargo xtask doc
+        run: cargo xtask book --output-path current
 
-      - name: Archive the API docs
-        run: |
-          cp -r target/doc apidocs
-          tar -cf apidocs.tar apidocs
+      - name: Archive the current documentation
+        run: tar -czf current-book.tar.gz current/
 
-      - name: Store the API docs
+      - name: Store the current API docs + book
         uses: actions/upload-artifact@v3
         with:
-          name: apidocs
-          path: apidocs.tar
-
-  # Build the books
-  mdbook:
-    name: build mdbook
-    needs: docs
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Install lychee
-        uses: taiki-e/install-action@v2
-        with:
-          tool: lychee
-
-      - name: Install mdbook
-        uses: taiki-e/install-action@v2
-        with:
-          tool: mdbook
+          name: current-book
+          path: current-book.tar.gz
 
-      - name: Install mdbook-mermaid
-        uses: taiki-e/install-action@v2
-        with:
-          tool: mdbook-mermaid
-
-      - name: Build book in English
-        run: cargo xtask book
-
-      - name: Download built API docs
-        uses: actions/download-artifact@v3
-        with:
-          name: apidocs
-
-      - name: Extract the API docs
-        run: tar -xf apidocs.tar 
-
-      - name: Check links
-        run: |
-          cargo xtask book --output-path book-target/current/ --api-docs apidocs/
-
-      - name: Archive the book + API docs
-        run: |
-          tar -cf book.tar book-target/current/
-
-      - name: Store the Book + API docs
-        uses: actions/upload-artifact@v3
-        with:
-          name: book
-          path: book.tar
+  # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149
+  #
+  # ALL THE PREVIOUS JOBS NEED TO BE ADDED TO THE `needs` SECTION OF THIS JOB!
 
-  mdbookold:
-    name: build docs and mdbook for older releases
-    needs: mergetostablebranch
+  ci-success:
+    name: ci
+    if: github.event_name == 'push' && success()
+    needs:
+      - formatcheck
+      - check
+      - clippy
+      - checkexamples
+      - testexamples
+      - tests
+      - current-book
     runs-on: ubuntu-22.04
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - 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: Fetch and build books for older versions
-        run: |
-          ./scripts/build-old-books.sh "${{ env.STABLE_VERSION }} ${{ env.OLDSTABLE_VERSION }}"
-
-      - name: Archive the old books
-        run: |
-          cd book-target
-          mv old mdbookold
-          tar -cf mdbookold.tar mdbookold
+      - name: Mark the job as a success
+        run: exit 0
 
-      - name: Store the old API docs
-        uses: actions/upload-artifact@v3
-        with:
-          name: mdbookold
-          path: mdbookold.tar
+  # All the steps below are for the book & archiving purposes
 
   parseversion:
     name: Parse the master branch RTIC version
@@ -377,7 +319,6 @@ jobs:
           echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV
           echo "version=$VERSION" >> $GITHUB_ENV
 
-
   # Update stable branch
   #
   # This is only valid when current stable resides in
@@ -387,7 +328,7 @@ jobs:
   # Thus, no need to push changes 
   #
   # This needs to run before book is built, as bookbuilding fetches from the branch
-  mergetostablebranch:
+  merge-to-stable-branch:
     name: Merge branch into release/vX when pushing to master
     runs-on: ubuntu-22.04
     needs:
@@ -403,6 +344,30 @@ jobs:
         if: ${{ env.versionmajor == env.STABLE_VERSION }}
         run: git push -u origin ${{ env.branch }}
 
+  old-books:
+    name: Build book and API docs for older versions
+    runs-on: ubuntu-22.04
+    needs:
+      - merge-to-stable-branch
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install book prerequisites
+        uses: ./.github/actions/book-prerequisites
+
+      # Build book for older releases
+      - name: Build old docs
+        run: ./scripts/build-old-books.sh "${{ env.STABLE_VERSION }} ${{ env.OLDSTABLE_VERSION }}"
+
+      - name: Archive the current documentation
+        run: tar -czf old-books.tar.gz old/
+
+      - name: Store the old versions of API docs + book
+        uses: actions/upload-artifact@v3
+        with:
+          name: old-books
+          path: old-books.tar.gz
+
   # Only runs when pushing to master branch
   # Bors run CI against staging branch,
   # if that succeeds Borst tries against master branch
@@ -411,66 +376,43 @@ jobs:
     name: deploy
     runs-on: ubuntu-22.04
     needs:
-      - mergetostablebranch
-      - docs      
-      - mdbookold      
-      - mdbook
+      - merge-to-stable-branch
+      - current-book
+      - old-books
 
     # 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: Install book prerequisites
+        uses: ./.github/actions/book-prerequisites
 
       - 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: current-book
 
       - 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: old-books
 
       - name: Prepare books
         shell: 'script --return --quiet --command "bash {0}"'
         run: |
-          export CURRENT_VERSION=${{ env.versionmajor }}
-          ./scripts/prep-books.sh "${{ env.STABLE_VERSION }} ${{ env.OLDSTABLE_VERSION }}"
+          tar xf current-book.tar.gz
+          tar xf old-books.tar.gz
+          CURRENT_VERSION=${{ env.versionmajor }} ./scripts/prep-books.sh "${{ env.STABLE_VERSION }} ${{ env.OLDSTABLE_VERSION }}"
 
       - name: Archive the webroot
-        run: |
-          cd book-target
-          mv deploy bookstodeploy
-          tar -cf bookstodeploy.tar bookstodeploy
+        run: tar -czf book-webroot.tar.gz deploy
 
       - name: Store the books
         uses: actions/upload-artifact@v3
         with:
-          name: bookstodeploy
-          path: bookstodeploy.tar
+          name: book-webroot
+          path: book-webroot.tar.gz
 
   ghapages:
     name: Publish rtic.rs
@@ -481,36 +423,14 @@ jobs:
       - name: Download books
         uses: actions/download-artifact@v3
         with:
-          name: bookstodeploy
+          name: book-webroot
 
       - name: Extract the books
-        run: |
-          tar -xf bookstodeploy.tar 
+        run: tar -xf book-webroot.tar.gz
 
       - name: Deploy to GH-pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./bookstodeploy
+          publish_dir: ./book-webroot
           force_orphan: true
-
-  # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149
-  #
-  # ALL THE PREVIOUS JOBS NEED TO BE ADDED TO THE `needs` SECTION OF THIS JOB!
-
-  ci-success:
-    name: ci
-    if: github.event_name == 'push' && success()
-    needs:
-      - formatcheck
-      - check
-      - clippy
-      - checkexamples
-      - testexamples
-      - tests
-      - docs
-      - mdbook
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Mark the job as a success
-        run: exit 0

scripts/build-old-books.sh

@@ -11,7 +11,7 @@ mkredirect(){
 
 clean_build_output=${CLEAN_BUILD_OUTPUT:-1}
 vers=($1)
-buildroot=${OLD_BOOK_BUILD_ROOT:-"book-target/old"}
+buildroot=${OLD_BOOKS_ROOT:-"book-target/old"}
 
 webroot=$buildroot/versions
 rm -rf $webroot
@@ -55,13 +55,13 @@ for ver in ${vers[@]}; do
 
     popd
 
-    rm -r $buildroot/$ver
+    rm -rf $buildroot/$ver
 done
 
 # Move all versions into the build root for easier access
 cp -r $webroot/* $buildroot
 
 if [ $clean_build_output -eq 1 ]; then
-    rm -r $srcdir
-    rm -r $webroot
+    rm -rf $srcdir
+    rm -rf $webroot
 fi