mp-units/.github/workflows/documentation.yml

# The MIT License (MIT)
#
# Copyright (c) 2018 Mateusz Pusz
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

name: Documentation

on:
  push:
    branches:
      - master
      - main
    tags:
      - v*
    paths:
      - "docs/**"
      - ".github/workflows/documentation.yml"
      - "CHANGELOG.md"
      - "CONTRIBUTING.md"
      - "mkdocs.yml"
permissions:
  contents: write
  pages: write
  id-token: write

# Serialize all documentation publishes into a single queue. The publish step
# force-pushes a rewritten (squashed) gh-pages branch, so concurrent runs for
# different refs (e.g. a tag release and a master push) must not overlap or they
# would clobber each other. Do not cancel in-progress runs: every deploy must
# complete so its version is recorded.
concurrency:
  group: ${{ github.workflow }}-publish
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v6
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@v5
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - name: Prepare git
        run: |
          git config --global user.name github-actions
          git config --global user.email github-actions@github.com
          git fetch origin gh-pages --depth=1
      - name: Installing API reference dependencies
        run: |
          sudo apt update
          sudo apt install latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended lmodern
          sudo apt install haskell-stack graphviz nodejs npm ghc cabal-install
          npm install split mathjax-full mathjax-node-sre mathjax-node-cli yargs@16.2.0
          cabal update
          echo "${{ github.workspace }}/node_modules/.bin" >> $GITHUB_PATH
      - name: Get git repos with API reference tools
        run: |
          git clone https://github.com/JohelEGP/jegp.cmake_modules.git --depth=1
          git clone https://github.com/JohelEGP/draft.git --branch=standardese_sources_base --depth=1
          git clone https://github.com/JohelEGP/cxxdraft-htmlgen.git --branch=standardese_sources_base --depth=1
      - name: Generate API reference
        run: |
          cmake -S docs/reference/api_reference/src -B build \
                -DCMAKE_MODULE_PATH="${{ github.workspace }}/jegp.cmake_modules/modules" \
                -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY="${{ github.workspace }}/draft" \
                -DJEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY="${{ github.workspace }}/cxxdraft-htmlgen"
          cmake --build build
          mv build/mp-units.html docs/reference/api_reference/gen
      - name: Installing pip dependencies
        run: |
          pip install conan mkdocs-material mkdocs-rss-plugin mkdocs-material[imaging] mkdocs-exclude mike
      - name: Building docs for a released version
        if: startsWith(github.event.ref, 'refs/tags/v')
        run: |
          mike deploy --update-aliases `conan inspect .  | sed -n -r 's/version: ([0-9]+.[0-9]+).[0-9]+/\1/p'`
      - name: Building docs for a development version
        if: ${{!startsWith(github.event.ref, 'refs/tags/v')}}
        run: |
          mike deploy --update-aliases HEAD latest
      - name: Squash history and publish gh-pages
        run: |
          # `mike deploy` (above, without --push) updated the local gh-pages branch
          # with the new build. GitHub Pages only ever serves the branch tip and the
          # whole site is regenerable, so we collapse gh-pages to a single parentless
          # commit before pushing. This keeps every versioned subtree and versions.json
          # intact (they live in the tree, not in history) while preventing the branch
          # from accumulating obsolete full-site snapshots that bloat the repo.
          tree=$(git rev-parse 'refs/heads/gh-pages^{tree}')
          commit=$(git commit-tree "$tree" -m "docs: published documentation site")
          git update-ref refs/heads/gh-pages "$commit"
          git push --force origin gh-pages

      - name: Generate documentation summary
        if: always()
        run: |
          echo "## 📖 Documentation Build Summary" >> $GITHUB_STEP_SUMMARY
          if [ "${{ job.status }}" = "success" ]; then
            echo "✅ **Documentation successfully built and deployed**" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            if [[ "${{ github.event.ref }}" == refs/tags/v* ]]; then
              echo "🏷️ **Release Documentation**: Published version-specific docs" >> $GITHUB_STEP_SUMMARY
              echo "📅 **Version**: \`$(conan inspect . | sed -n -r 's/version: ([0-9]+.[0-9]+).[0-9]+/\1/p')\`" >> $GITHUB_STEP_SUMMARY
            else
              echo "🚀 **Development Documentation**: Published to 'latest'" >> $GITHUB_STEP_SUMMARY
              echo "🔗 **Branch**: \`${{ github.ref_name }}\`" >> $GITHUB_STEP_SUMMARY
            fi
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "🌐 **Live Documentation**: https://mpusz.github.io/units/" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ **Documentation build failed**" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "Please check the build logs for API reference generation or MkDocs issues." >> $GITHUB_STEP_SUMMARY
          fi