name: akbasic Release Build
run-name: ${{ gitea.actor }} akbasic release checks
# Manual only. Nothing here runs on push: documentation is a release gate, not
# a per-commit check. The expensive mutation suite has its own daily schedule.
on:
  workflow_dispatch:

jobs:
  # Moved here from ci.yaml. The docs are wanted for a release, not on every
  # push.
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
        # No submodules at all. Doxyfile's INPUT is include/akbasic, src and
        # examples, none of which live under deps/, and doxygen does not need to
        # resolve <akerror.h> to parse a declaration. Verified by running it
        # against a tree with no deps/ present.
      - name: dependencies
        run: |
          sudo apt-get update -y
          sudo apt-get install -y doxygen graphviz
      # This is a gate, not a convenience. The Doxyfile sets
      # WARN_AS_ERROR = FAIL_ON_WARNINGS, so a doc block that documents some of a
      # function's parameters but not all of them fails the build. All 114 public
      # declarations under include/akbasic carry a @brief, a @param per
      # parameter, a @return and their @throws; keep it that way.
      #
      # OUTPUT_DIRECTORY is build/docs and doxygen will not create a missing
      # parent, so make it first -- there is no cmake step in this job to do it.
      - name: build API documentation
        run: |
          mkdir -p build
          doxygen Doxyfile
      - name: upload API documentation
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-documentation
          path: build/docs/html/
          if-no-files-found: error
      - run: echo "🍏 This job's status is ${{ job.status }}."
