From 518e995b2c4e2049122f822163a5d0fefadb83c7 Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Thu, 7 Mar 2024 13:58:25 +0000 Subject: [PATCH] Add a workflow to build and deploy `esp-hal` documentation to GitHub Pages (#1248) * update workflow * Format `index.html`, update the URLs, add favicon, various other minor tweaks * Move script into `.github/scripts`, add the package version to documentation path * Split the building and deployment of documentation into its own workflow --------- Co-authored-by: Kirill Mikhailov --- .github/scripts/build_docs.sh | 25 +++++ .github/workflows/documentation.yml | 50 ++++++++++ resources/.prettierrc.json | 4 + resources/esp-rs.svg | 4 + resources/index.html | 142 ++++++++++++++++++++++++++++ 5 files changed, 225 insertions(+) create mode 100755 .github/scripts/build_docs.sh create mode 100644 .github/workflows/documentation.yml create mode 100644 resources/.prettierrc.json create mode 100644 resources/esp-rs.svg create mode 100644 resources/index.html diff --git a/.github/scripts/build_docs.sh b/.github/scripts/build_docs.sh new file mode 100755 index 000000000..7390ab5c3 --- /dev/null +++ b/.github/scripts/build_docs.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash + +set -euo pipefail + +# Extract the package version from `esp-hal` (using arcane methods): +PKG_VERSION=$( + cargo metadata --format-version=1 --no-deps --manifest-path=esp-hal/Cargo.toml \ + | jq -r '.packages[] | select(.name=="esp-hal") | .version' +) + +# Build the documentation for each supported cheap, namespacing by +# package version and chip: +CHIPS=("esp32" "esp32c2" "esp32c3" "esp32c6" "esp32h2" "esp32p4" "esp32s2" "esp32s3") + +for CHIP in "${CHIPS[@]}"; do + cargo xtask build-documentation \ + --output-path="docs/$PKG_VERSION"/"$CHIP"/ \ + esp-hal \ + "$CHIP" +done + +# Copy any additional resources (such as the index and our logo) +# to the location of the built documentation as well: +cp resources/esp-rs.svg docs/ +cp resources/index.html docs/ diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 000000000..5e9ddd10b --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,50 @@ +name: Documentation + +on: + workflow_dispatch: + +env: + CARGO_TERM_COLOR: always + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: esp-rs/xtensa-toolchain@v1.5 + with: + default: true + ldproxy: false + + - name: Build documentation + run: ./.github/scripts/build_docs.sh + + # https://github.com/actions/deploy-pages/issues/303#issuecomment-1951207879 + - name: Remove problematic '.lock' files + run: find docs -name ".lock" -exec rm -f {} \; + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: "docs" + + deploy: + # Add a dependency to the build job: + needs: build + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment: + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + + # Deploy to the github-pages environment: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + # Specify runner + deployment step: + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/resources/.prettierrc.json b/resources/.prettierrc.json new file mode 100644 index 000000000..1d43a318a --- /dev/null +++ b/resources/.prettierrc.json @@ -0,0 +1,4 @@ +{ + "printWidth": 100, + "tabWidth": 2 +} diff --git a/resources/esp-rs.svg b/resources/esp-rs.svg new file mode 100644 index 000000000..d90b9eaf3 --- /dev/null +++ b/resources/esp-rs.svg @@ -0,0 +1,4 @@ + + + + diff --git a/resources/index.html b/resources/index.html new file mode 100644 index 000000000..0ae543ac7 --- /dev/null +++ b/resources/index.html @@ -0,0 +1,142 @@ + + + + + + + esp-rs docs + + + + + + + + +
+ + + + +
+ esp32 + esp-hal (targeting ESP32) + 0.15.0 +
+ +
+ esp32c2 + esp-hal (targeting ESP32-C2) + 0.15.0 +
+ +
+ esp32c3 + esp-hal (targeting ESP32-C3) + 0.15.0 +
+ +
+ esp32c6 + esp-hal (targeting ESP32-C6) + 0.15.0 +
+ +
+ esp32h2 + esp-hal (targeting ESP32-H2) + 0.15.0 +
+ +
+ esp32p4 + esp-hal (targeting ESP32-P4) + 0.15.0 +
+ +
+ esp32s2 + esp-hal (targeting ESP32-S2) + 0.15.0 +
+ +
+ esp32s3 + esp-hal (targeting ESP32-S3) + 0.15.0 +
+
+ +