full-help-docs.yml

name: CLI Help Doc

on:
  push:
    branches: [main, release/**]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref_protected == 'true' && github.sha || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read
  # Optional: allow read access to pull request. Use with `only-new-issues` option.
  pull-requests: read

jobs:
  complete:
    if: always()
    needs: [doc-check]
    runs-on: ubuntu-latest
    steps:
    - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
      run: exit 1

  doc-check:
    runs-on: ubuntu-latest-16-cores
    steps:
    - uses: actions/checkout@v4
    - uses: stellar/actions/rust-cache@main
    - run: rustup update
    - name: Generate help doc
      # this looks goofy to get GITHUB_OUTPUT to work with multi-line return values;
      # see https://stackoverflow.com/a/74266196/249801
      run: |
        make generate-full-help-doc
        raw_diff=$(git diff FULL_HELP_DOCS.md)
        if [ "$raw_diff" != "" ]; then echo ""; echo "Unexpected docs change:"; echo "======================="; echo ""; echo "$raw_diff"; echo ""; echo "======================="; echo ""; fi
        echo diff=$raw_diff >> $GITHUB_OUTPUT
      id: doc-gen

    - name: Check diff
      if: steps.doc-gen.outputs.diff != ''
      uses: actions/github-script@v7
      with:
        script: |
          core.setFailed('Expected `doc-gen` to generate no diffs, but got diff shown in previous step.\n\nUpdate the full help docs:\n\n    cargo md-gen\n\nDo this automatically on every commit by installing the pre-commit hook as explained in the README.')