Documentation #46
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 structure describing the packages to build. | |
| E.g: [{"name":"esp-hal","tag":"v0.23.1"},{"name":"esp-wifi","tag":"esp-wifi-v0.12"}] | |
| NOTE: You can run `cargo xtask tag-releases` to get the json output generated for this workflow. | |
| required: true | |
| server: | |
| type: choice | |
| description: Which server to deploy to | |
| options: | |
| - preview | |
| - production | |
| env: | |
| CARGO_TERM_COLOR: always | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| jobs: | |
| setup: | |
| runs-on: ubuntu-latest | |
| outputs: | |
| packages: '${{ github.event.inputs.packages }}' | |
| steps: | |
| - run: echo "Setup complete!" | |
| 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.85.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: esp-rs/esp-hal | |
| 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 |