doc.yml

name: Docs
on:
  push:
    branches: [🦆, 📝-*]
permissions:
  contents: write

jobs:
  check:
    name: Build and deploy docs
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Install Rust
        # FIXME: Switch back when actions-rs/toolchain#{209,220,222} is merged
        uses: r3-os/actions-rust-toolchain@a862b6623c178b43a3135516442a5f72fb5c1877
        with:
          profile: minimal

      - name: Install dependencies (Linux)
        run: .github/scripts/install-deno.sh
      - name: Set rustdoc flags
        run: |
          # [ref:doc_global_styling]
          echo "RUSTDOCFLAGS=--html-in-header `pwd`/src/r3/src/common.md" >> $GITHUB_ENV

      - name: Build API documentation
        # FIXME: Switch back when actions-rs/cargo#217 gets merged
        uses: r3-os/actions-rust-cargo@fb222fe18dc90e381546d012f9e3d6f353f0f627
        with:
          command: doc
          # Documentate all published packages with all features enabled [tag:doc_all_features]
          args: -p r3_port_std -p r3_port_arm -p r3_port_arm_m -p r3_port_riscv -p r3_support_rp2040 -p r3_support_rza1 -p r3_portkit -p r3_kernel -p r3 -p r3_core --all-features

      - name: Redirect non-local crate documentation to docs.rs
        run: |
          deno --version
          deno run -A scripts/externalize-non-local-docs.ts -y

      - name: Check output
        run: |
          # Don't fail the pipeline on errors because they are mostly minor
          deno run --allow-read scripts/check-doc.ts || true

      - name: Generate badge
        run: |
          rev=`git show-ref --head HEAD | cut -b 1-7`
          wget -nv -O target/doc/badge.svg "https://img.shields.io/badge/docs-$rev-ok?style=for-the-badge"

      - name: Collect output
        run: |
          mkdir output
          mv target/doc output

      - name: Copy assets
        run: |
          cp doc/logo-small.svg output
          wget -nv -O output/404.html "https://r3-os.github.io/404.html"
          touch output/.nojekyll

      # If we are on the main branch, deploy it to the website
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4.4.1
        if: github.ref == 'refs/heads/🦆'
        with:
          branch: gh-pages
          folder: output
          single-commit: true
          force: true

      # Otherwise, put it on the Actions page to allow download
      - name: Archive output
        if: github.ref != 'refs/heads/🦆'
        # use tar + compressor for faster upload and smaller artifact size
        run: |
          cd output
          tar -cv doc | xz > r3-api-docs.tar.xz

      - name: Upload output as artifact
        uses: actions/upload-artifact@v2
        if: github.ref != 'refs/heads/🦆'
        with:
          name: r3-api-docs
          path: output/r3-api-docs.tar.xz