Documentation #35
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Documentation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| packages: | |
| description: > | |
| A JSON array of tags to build documentation for: | |
| ["esp-hal-v0.23.0", "esp-wifi-v0.12"] | |
| will build docs for [email protected] and [email protected] | |
| required: true | |
| server: | |
| type: choice | |
| description: Which server to deploy to | |
| options: | |
| - preview | |
| - production | |
| env: | |
| CARGO_TERM_COLOR: always | |
| jobs: | |
| setup: | |
| runs-on: ubuntu-latest | |
| outputs: | |
| # convert the tag list into a list of packages and tags | |
| # echo '["esp-alloc-v0.6.0","esp-backtrace-v0.15.0"]' | jq '[.[] | {name: (split("-v")[0]), tag: .}]' | |
| # [ | |
| # { | |
| # "name": "esp-alloc", | |
| # "tag": "esp-alloc-v0.6.0" | |
| # }, | |
| # { | |
| # "name": "esp-backtrace", | |
| # "tag": "esp-backtrace-v0.15.0" | |
| # } | |
| #] | |
| packages: ${{ steps.output.outputs.packages }} | |
| steps: | |
| - id: output | |
| run: | | |
| echo "packages=$(jq '[.[] | {name: (split(\"-v\")[0]), tag: .}]' <<< ${{ github.event.inputs.packages }})" >> "$GITHUB_OUTPUT" | |
| build: | |
| needs: setup | |
| strategy: | |
| fail-fast: true | |
| matrix: | |
| packages: ${{ fromJson(needs.setup.outputs.packages) }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: esp-rs/[email protected] | |
| with: | |
| default: true | |
| ldproxy: false | |
| version: 1.84.0.0 | |
| # TODO: we could build this once and download onto each runner | |
| # Build the `xtask` package using the latest commit, and copy the | |
| # resulting binary to the `~/.cargo/bin/` directory. We do this to | |
| # avoid having to rebuild different versions of the package for | |
| # different tags if they do not fall on the same commit, and to | |
| # make sure that we take advantage of any subsequent updates to | |
| # the xtask which may have happened after a release was tagged. | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: esp-rs/esp-hal | |
| - name: Build xtask | |
| run: | | |
| cargo build --release --package=xtask --features=deploy-docs | |
| cp target/release/xtask ~/.cargo/bin/hal-xtask | |
| # Checkout the tag we need to start building the docs | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: mabezdev/esp-hal # FIXME change | |
| ref: ${{ matrix.packages.tag }} | |
| - name: Build documentation | |
| run: hal-xtask build-documentation --packages=${{ matrix.packages.name }} --base-url /projects/rust/ | |
| # 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 docs for ${{ matrix.packages.name }} | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: ${{ matrix.packages.name }} | |
| path: "docs/${{ matrix.packages.name }}" | |
| assemble: | |
| needs: [setup, build] | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: dtolnay/rust-toolchain@v1 | |
| with: | |
| toolchain: stable | |
| - name: Prepare | |
| run: mkdir docs && mkdir docs/esp-hal && mkdir docs/esp-wifi && mkdir docs/esp-lp-hal | |
| - name: Download all docs | |
| uses: actions/download-artifact@v4 | |
| with: | |
| path: "docs/" | |
| # Create an index for _all_ packages. | |
| - name: Create index.html | |
| run: cargo xtask build-documentation-index | |
| - if: ${{ github.event.inputs.server == 'preview' }} | |
| name: Deploy to preview server | |
| uses: appleboy/[email protected] | |
| with: | |
| host: preview-docs.espressif.com | |
| username: ${{ secrets.PREVIEW_USERNAME }} | |
| key: ${{ secrets.PREVIEW_KEY }} | |
| target: ${{ secrets.PREVIEW_TARGET }} | |
| source: "docs/" | |
| strip_components: 1 # remove the docs prefix | |
| overwrite: true | |
| - if: ${{ github.event.inputs.server == 'production' }} | |
| name: Deploy to production server | |
| uses: appleboy/[email protected] | |
| with: | |
| host: docs.espressif.com | |
| username: ${{ secrets.PRODUCTION_USERNAME }} | |
| key: ${{ secrets.PRODUCTION_KEY }} | |
| target: ${{ secrets.PRODUCTION_TARGET }} | |
| source: "docs/" | |
| strip_components: 1 # remove the docs prefix | |
| overwrite: true |