Merge pull request #38 from hispark-rs/docs/peripheral-dma-design-0.5.1 #54
This file contains hidden or 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: | |
| push: | |
| branches: [main, master] | |
| paths: | |
| - 'crates/hisi-riscv-hal/src/**' | |
| - 'crates/hisi-riscv-hal/Cargo.toml' | |
| - 'crates/pac/ws63-pac/src/**' | |
| - 'docs/**' | |
| pull_request: | |
| branches: [main, master] | |
| paths: | |
| - 'crates/hisi-riscv-hal/src/**' | |
| - 'crates/pac/ws63-pac/src/**' | |
| - 'docs/**' | |
| env: | |
| CARGO_TERM_COLOR: always | |
| jobs: | |
| # ── Build API docs ──────────────────────────────────────────── | |
| docs: | |
| name: Build API Documentation | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v5 | |
| with: | |
| submodules: recursive | |
| - name: Install hisi-riscv toolchain | |
| run: bash .github/scripts/install-toolchain.sh | |
| - name: Cache cargo registry | |
| uses: actions/cache@v5 | |
| with: | |
| # registry/git only — target/ is toolchain-specific (see ci.yml note). | |
| path: | | |
| ~/.cargo/registry/ | |
| ~/.cargo/git/ | |
| key: ${{ runner.os }}-cargo-ws63-docs-${{ hashFiles('**/Cargo.lock') }} | |
| restore-keys: ${{ runner.os }}-cargo-ws63-docs- | |
| - name: Install mdBook | |
| uses: taiki-e/install-action@v2 | |
| with: | |
| tool: mdbook | |
| - name: Build the mdBook handbook (docs/ -> docs/book) | |
| run: mdbook build docs | |
| - name: Build API documentation (hisi-riscv-hal/pac/rt) | |
| # hisi-riscv-hal has no default chip (0.5.0); select chip-ws63 so its | |
| # `soc::pac`/`soc::chip` resolve and the no-chip compile_error stays silent. | |
| run: cargo doc -p hisi-riscv-hal -p ws63-pac -p hisi-riscv-rt --no-deps --features hisi-riscv-hal/chip-ws63 | |
| - name: Assemble the site (handbook at /, rustdoc under /api) | |
| run: | | |
| rm -rf site && mkdir -p site/api | |
| cp -r docs/book/. site/ | |
| cp -r target/riscv32imfc-unknown-none-elf/doc/. site/api/ | |
| # rustdoc has no root index.html; redirect /api/ to the HAL crate's docs. | |
| printf '<!doctype html><meta http-equiv="refresh" content="0; url=hisi_riscv_hal/index.html">\n' > site/api/index.html | |
| - name: Upload docs artifact | |
| uses: actions/upload-artifact@v6 | |
| with: | |
| name: api-docs | |
| path: site/ | |
| # ── Deploy to GitHub Pages ──────────────────────────────────── | |
| deploy: | |
| name: Deploy to GitHub Pages | |
| runs-on: ubuntu-latest | |
| needs: docs | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| permissions: | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Download docs artifact | |
| uses: actions/download-artifact@v7 | |
| with: | |
| name: api-docs | |
| path: docs-output | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v6 | |
| with: | |
| # Auto-enable Pages on first run (the repo was renamed to hisi-riscv-rs; | |
| # Pages must be sourced from GitHub Actions). If this still 404s, enable | |
| # it once in Settings -> Pages -> Source: GitHub Actions. | |
| enablement: true | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs-output | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v5 | |
| # ── Link check ──────────────────────────────────────────────── | |
| link-check: | |
| name: Check Links | |
| runs-on: ubuntu-latest | |
| continue-on-error: true | |
| steps: | |
| - uses: actions/checkout@v5 | |
| - name: Check markdown links | |
| uses: lycheeverse/lychee-action@v2 | |
| with: | |
| # lychee.toml scopes the check to this repo's own docs (excludes submodule | |
| # trees — separate repos — and the TLS-broken blog.japaric.io reference). | |
| args: --config lychee.toml --verbose --no-progress '*.md' '**/*.md' | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |