deploy-docs.yml

name: Deploy Documentation (GitHub Pages)

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build-and-deploy:
    name: Build the documentation site and deploy to GitHub Pages
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # The full history is required to compute the
          # 1.0.<commit-count>.<short-sha> project version.
          fetch-depth: 0

      - name: Install Doxygen
        uses: ssciwr/doxygen-install@v2.0.3
        with:
          # The latest stable release the documentation was generated and
          # validated with.
          version: 1.18.0

      - name: Install Graphviz
        uses: ts-graphviz/setup-graphviz@v2.0.2

      - name: Generate the Doxygen configuration file
        run: |
          PROJECT_VERSION="1.0.$(git rev-list --count HEAD).$(git rev-parse --short HEAD)"
          # The version placeholder is the only build-time substitution;
          # the HTML output goes to docs/api/ (OUTPUT_DIRECTORY +
          # HTML_OUTPUT, see doxygen.conf.in), so the MkDocs build serves
          # it as the /api/ section of the site.
          sed -e "s|@OPENSIMPLEX2_VERSION@|${PROJECT_VERSION}|" \
              doxygen.conf.in > doxygen.conf
          grep -E '^(PROJECT_NAME|PROJECT_NUMBER)' doxygen.conf

      - name: Generate the Doxygen HTML documentation
        run: doxygen doxygen.conf

      - name: Copy the README and the LICENSE as the site home page assets
        run: |
          # docs/index.md is generated from the root README.md at build
          # time (it is gitignored), so the README stays the single
          # source of truth for the site home page. The LICENSE file is
          # copied too, because the README links it relatively and
          # `mkdocs build --strict` fails on unresolved relative links.
          mkdir -p docs
          cp README.md docs/index.md
          cp LICENSE docs/

      - name: Install MkDocs and the Material theme
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs==1.6.1 mkdocs-material==9.7.7

      - name: Build the documentation site
        run: |
          mkdocs build --strict
          ls -la site site/api | head -40

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: site
          clean: true