docs: versioning clarity, measured performance guidance, and fail-clo… #3878
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: github pages | |
| on: | |
| push: | |
| branches: | |
| - master | |
| tags: | |
| - v* | |
| workflow_dispatch: | |
| inputs: | |
| version: | |
| description: "Release tag to backfill (for example, v0.70.2); leave empty to publish master" | |
| required: false | |
| type: string | |
| env: | |
| RUST_VERSION: 1.93.0 | |
| permissions: | |
| contents: write | |
| jobs: | |
| deploy: | |
| runs-on: warp-ubuntu-latest-x64-2x # needs at least 100 gb hdd | |
| steps: | |
| - uses: actions/checkout@v6 | |
| with: | |
| ref: ${{ inputs.version || github.ref }} | |
| - name: Resolve documentation target | |
| id: docs_target | |
| env: | |
| REQUESTED_VERSION: ${{ inputs.version }} | |
| run: | | |
| if [[ -n "$REQUESTED_VERSION" ]]; then | |
| checked_out_tag="$(git describe --tags --exact-match)" | |
| if [[ "$checked_out_tag" != "$REQUESTED_VERSION" ]]; then | |
| echo "Requested $REQUESTED_VERSION but checked out $checked_out_tag" >&2 | |
| exit 1 | |
| fi | |
| echo "tag=$REQUESTED_VERSION" >> "$GITHUB_OUTPUT" | |
| elif [[ "$GITHUB_REF" == refs/tags/* ]]; then | |
| echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT" | |
| elif [[ "$GITHUB_REF" != refs/heads/master ]]; then | |
| echo "Refusing to publish master documentation from $GITHUB_REF" >&2 | |
| echo "Select an exact release tag with the version input instead." >&2 | |
| exit 1 | |
| else | |
| echo "tag=" >> "$GITHUB_OUTPUT" | |
| fi | |
| - uses: Swatinem/rust-cache@v2 | |
| - name: Install toolchain | |
| uses: dtolnay/rust-toolchain@master | |
| with: | |
| toolchain: ${{ env.RUST_VERSION }} | |
| - name: Install Forc | |
| run: cargo install --locked --debug --path ./forc | |
| - name: Install Forc plugins | |
| env: | |
| DOCS_TAG: ${{ steps.docs_target.outputs.tag }} | |
| run: | | |
| cargo uninstall forc-mcp || true | |
| rm -f "${CARGO_HOME:-$HOME/.cargo}/bin/forc-mcp" | |
| if [[ -d ./forc-plugins/forc-client ]]; then | |
| # Before the plugin repository split, release tags carried these | |
| # plugins in-tree. Use those exact sources when backfilling docs. | |
| for plugin in forc-client forc-crypto forc-mcp forc-node; do | |
| if [[ -d "./forc-plugins/$plugin" ]]; then | |
| cargo install --locked --debug --path "./forc-plugins/$plugin" | |
| fi | |
| done | |
| elif [[ -z "$DOCS_TAG" ]]; then | |
| # Default-branch documentation follows the current plugin sources. | |
| cargo install --locked --debug --git https://github.com/FuelLabs/forc forc-client | |
| cargo install --locked --debug --git https://github.com/FuelLabs/forc forc-crypto | |
| cargo install --locked --debug --git https://github.com/FuelLabs/forc forc-node | |
| elif [[ "$DOCS_TAG" == v0.71.2 ]]; then | |
| # Post-split plugins release independently. Pin the compatibility | |
| # set recorded for Sway v0.71.2 in FuelLabs/forc releases.toml. | |
| cargo install --locked --debug --git https://github.com/FuelLabs/forc --tag forc-client-0.71.3 forc-client | |
| cargo install --locked --debug --git https://github.com/FuelLabs/forc --tag forc-crypto-0.71.1 forc-crypto | |
| cargo install --locked --debug --git https://github.com/FuelLabs/forc --tag forc-node-0.71.3 forc-node | |
| else | |
| echo "No independent Forc plugin compatibility set is recorded for $DOCS_TAG" >&2 | |
| echo "Add exact plugin tags before publishing this release's command reference." >&2 | |
| exit 1 | |
| fi | |
| for plugin in forc-debug forc-fmt forc-doc forc-lsp forc-migrate forc-publish; do | |
| if [[ -d "./forc-plugins/$plugin" ]]; then | |
| cargo install --locked --debug --path "./forc-plugins/$plugin" | |
| fi | |
| done | |
| - name: Install mdbook-forc-documenter | |
| run: cargo install --locked --debug --path ./scripts/mdbook-forc-documenter | |
| - name: Setup mdBook | |
| uses: peaceiris/actions-mdbook@v1 | |
| with: | |
| mdbook-version: "0.4.45" | |
| - name: Build Sway book | |
| run: MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs/book | |
| - name: Build Sway reference | |
| run: mdbook build docs/reference | |
| - name: Build Sway std library | |
| run: forc doc --path ./sway-lib-std | |
| - name: Deploy master std | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./sway-lib-std/out/doc | |
| destination_dir: master | |
| if: steps.docs_target.outputs.tag == '' | |
| - name: Deploy master book | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/book/book | |
| destination_dir: master/book | |
| if: steps.docs_target.outputs.tag == '' | |
| - name: Deploy master reference | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/reference/book | |
| destination_dir: master/reference | |
| if: steps.docs_target.outputs.tag == '' | |
| - name: Create master book redirect file | |
| run: | | |
| mkdir ./tmp | |
| cat > ./tmp/index.html <<EOF | |
| <!DOCTYPE html> | |
| <meta charset="utf-8"> | |
| <meta http-equiv="refresh" content="0; URL=../master/book"> | |
| <link rel="canonical" href="../master/book"> | |
| EOF | |
| if: steps.docs_target.outputs.tag == '' | |
| - name: Deploy index.html redirect file to master | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./tmp | |
| destination_dir: ./master | |
| keep_files: true | |
| if: steps.docs_target.outputs.tag == '' | |
| - name: Deploy book tag | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/book/book | |
| destination_dir: ${{ steps.docs_target.outputs.tag }}/book | |
| if: steps.docs_target.outputs.tag != '' | |
| - name: Deploy reference tag | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/reference/book | |
| destination_dir: ${{ steps.docs_target.outputs.tag }}/reference | |
| if: steps.docs_target.outputs.tag != '' | |
| - name: Deploy std tag | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./sway-lib-std/out/doc/std | |
| destination_dir: ${{ steps.docs_target.outputs.tag }}/std | |
| if: steps.docs_target.outputs.tag != '' | |
| - name: Create tag book redirect file | |
| run: | | |
| mkdir ./tmp | |
| cat > ./tmp/index.html <<EOF | |
| <!DOCTYPE html> | |
| <meta charset="utf-8"> | |
| <meta http-equiv="refresh" content="0; URL=../${{ steps.docs_target.outputs.tag }}/book"> | |
| <link rel="canonical" href="../${{ steps.docs_target.outputs.tag }}/book"> | |
| EOF | |
| if: steps.docs_target.outputs.tag != '' | |
| - name: Deploy index.html redirect file to tag | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./tmp | |
| destination_dir: ./${{ steps.docs_target.outputs.tag }} | |
| keep_files: true | |
| if: steps.docs_target.outputs.tag != '' | |
| - name: Create latest HTML redirect file | |
| if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') | |
| run: | | |
| mkdir ./latest | |
| cat > ./latest/index.html <<EOF | |
| <!DOCTYPE html> | |
| <meta charset="utf-8"> | |
| <meta http-equiv="refresh" content="0; URL=../${{ steps.docs_target.outputs.tag }}/book"> | |
| <link rel="canonical" href="../${{ steps.docs_target.outputs.tag }}/book"> | |
| EOF | |
| - name: Set latest to point to tag | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./latest/ | |
| destination_dir: ./latest/ | |
| if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') |