From e88e3cbca616413ecf5804b930e67f4b3323238b Mon Sep 17 00:00:00 2001 From: datdenkikniet Date: Sun, 21 May 2023 12:40:42 +0200 Subject: [PATCH] Consolidate the book & API building steps --- .github/actions/book-prerequisites/action.yml | 20 ++ .github/workflows/build.yml | 234 ++++++------------ scripts/build-old-books.sh | 8 +- scripts/prep-books.sh | 33 ++- xtask/src/argument_parsing.rs | 2 +- 5 files changed, 118 insertions(+), 179 deletions(-) create mode 100644 .github/actions/book-prerequisites/action.yml diff --git a/.github/actions/book-prerequisites/action.yml b/.github/actions/book-prerequisites/action.yml new file mode 100644 index 000000000000..51ed6a63d01e --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 8499114d2447..c9d43e5f19f1 100644 --- a/.github/workflows/build.yml +++ b/.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 diff --git a/scripts/build-old-books.sh b/scripts/build-old-books.sh index 71475c89855e..8cf3de32171e 100755 --- a/scripts/build-old-books.sh +++ b/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 diff --git a/scripts/prep-books.sh b/scripts/prep-books.sh index 72e260822842..7acf33ed56f2 100755 --- a/scripts/prep-books.sh +++ b/scripts/prep-books.sh @@ -10,9 +10,8 @@ mkredirect() { langs=( en ) devver=( dev ) vers=( $1 ) -buildroot=${BOOK_BUILD_ROOT:-"book-target/deploy"} -oldbooks=${OLD_BOOK_BUILD_ROOT:-"book-target/old"} -oldbooks="$oldbooks/output" +webroot=${WEB_ROOT:-"book-target/deploy"} +oldbooks=${OLD_BOOKS_ROOT:-"book-target/old"} current_book=${CURRENT_BOOK_ROOT:-"book-target/current"} stable="${vers[0]}" @@ -28,37 +27,37 @@ echo "Latest stable version: $stable" echo "Current crate version: $crate_version" # Create directories -rm -rf $buildroot -mkdir -p $buildroot/$devver +rm -rf $webroot +mkdir -p $webroot/$devver # Copy the current dev version echo "Copy current dev version" -cp -r $current_book/* $buildroot/$devver +cp -r $current_book/* $webroot/$devver echo "Inserting redirects" # Replace relevant links to make rtic.rs/meeting/index.html # redirect to the meeting and make the text a bit more descriptive -mkredirect "https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg" $buildroot/meeting/index.html +mkredirect "https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg" $webroot/meeting/index.html sed -e "s|Page Redirection|RTIC Meeting|g" \ -e "s|If you|Redirecting to RTIC HackMD. If you|g" \ - -i $buildroot/meeting/index.html + -i $webroot/meeting/index.html # Redirect the main site to the stable release -mkredirect "$stable" $buildroot/index.html +mkredirect "$stable" $webroot/index.html # Create redirects for the dev version if [ "$stable" != "$crate_version" ]; then # Current stable version being built differ # so we want to display the current dev version echo "Redirecting dev version dev version files" - mkredirect "rtic/index.html" $buildroot/$devver/api/index.html - mkredirect "book/en" $buildroot/$devver/index.html + mkredirect "rtic/index.html" $webroot/$devver/api/index.html + mkredirect "book/en" $webroot/$devver/index.html else # The stable and crate version are the same # so we redirec to the stable version instead echo "Redirecting dev version to stable" - mkredirect "https://rtic.rs/$stable/api/rtic" $buildroot/$devver/api/index.html - mkredirect "https://rtic.rs/$stable" $buildroot/$devver/index.html + mkredirect "https://rtic.rs/$stable/api/rtic" $webroot/$devver/api/index.html + mkredirect "https://rtic.rs/$stable" $webroot/$devver/index.html fi # Pack up all of the older versions, including stable @@ -66,14 +65,14 @@ fi echo "Copying stable" # Copy the stable book to the stable alias -cp -r $oldbooks/$stable $buildroot/stable +cp -r $oldbooks/$stable $webroot/stable echo "Copying older versions" # Copy the stable book to the webroot -cp -r $oldbooks/$stable $buildroot/ +cp -r $oldbooks/$stable $webroot/ # Copy the old stable book to the webroot -cp -r $oldbooks/$oldstable $buildroot/ +cp -r $oldbooks/$oldstable $webroot/ # Forward CNAME file -cp CNAME $buildroot +cp CNAME $webroot diff --git a/xtask/src/argument_parsing.rs b/xtask/src/argument_parsing.rs index 6904c6a0304b..d6544243e465 100644 --- a/xtask/src/argument_parsing.rs +++ b/xtask/src/argument_parsing.rs @@ -399,7 +399,7 @@ pub struct BookArgs { /// The path to which the contents of the book should /// be written. - #[clap(long, short, default_value = "book-target")] + #[clap(long, short, default_value = "book-target/current")] pub output_path: String, /// Additional arguments to pass to `mdbook`