docs.yml

#
# Copyright (c) 2026 Steve Gerbino
# Copyright (c) 2026 Michael Vandeberg
#
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#
# Official repository: https://github.com/cppalliance/corosio/
#

name: Documentation

on:
  push:
    branches:
      - master
      - develop*
    paths:
      - 'doc/**'
      - 'include/**'
      - 'test/doc/reference/**'
      - '*.adoc'
      - 'README.adoc'
      - '.github/workflows/docs.yml'
  pull_request:
    paths:
      - 'doc/**'
      - 'include/**'
      - 'test/doc/reference/**'
      - '*.adoc'
      - 'README.adoc'
      - '.github/workflows/docs.yml'

jobs:
  antora:
    name: Antora Docs
    runs-on: 'ubuntu-latest'
    defaults:
      run:
        shell: bash
    steps:
      - name: Install packages
        uses: alandefreitas/cpp-actions/package-install@v1.9.0
        with:
          apt-get: git cmake

      - name: Clone Boost.Corosio
        uses: actions/checkout@v4
        with:
          path: corosio-root

      - name: Resolve Capy branch
        id: capy-ref
        uses: ./corosio-root/.github/actions/resolve-capy

      - name: Clone Capy
        uses: actions/checkout@v4
        with:
          repository: ${{ steps.capy-ref.outputs.repo }}
          ref: ${{ steps.capy-ref.outputs.ref }}
          path: capy-root

      - name: Clone Boost
        uses: alandefreitas/cpp-actions/boost-clone@v1.9.0
        id: boost-clone
        with:
          branch: ${{ (github.ref_name == 'master' && github.ref_name) || 'develop' }}
          boost-dir: boost-source
          modules-exclude-paths: ''
          scan-modules-dir: corosio-root
          scan-modules-ignore: corosio,capy

      - name: Patch Boost
        id: patch
        shell: bash
        run: |
          set -xe
          pwd
          ls
          ls -lah boost-source

          # Identify boost module being tested
          module=${GITHUB_REPOSITORY#*/}
          echo "module=$module" >> $GITHUB_OUTPUT

          # Identify GitHub workspace root
          workspace_root=$(echo "$GITHUB_WORKSPACE" | sed 's/\\/\//g')
          echo -E "workspace_root=$workspace_root" >> $GITHUB_OUTPUT

          # Remove module from boost-source
          rm -r "boost-source/libs/$module" || true
          rm -r "boost-source/libs/capy" || true

          # boost-clone uses sparse checkout which excludes CMakeLists.txt files
          # Disable sparse checkout to get full source trees for add_subdirectory in cmake_test
          cd boost-source
          if git sparse-checkout list > /dev/null 2>&1; then
            echo "Disabling sparse checkout..."
            git sparse-checkout disable
            echo "Fetching any missing objects..."
            git fetch origin --no-tags
            git checkout
          fi
          echo "Verifying libs/mp11/CMakeLists.txt exists..."
          ls -la libs/mp11/CMakeLists.txt || echo "WARNING: libs/mp11/CMakeLists.txt not found!"
          cd ..

          # Copy cached boost-source to an isolated boost-root
          cp -rL boost-source boost-root

          # Set boost-root output
          cd boost-root
          boost_root="$(pwd)"
          boost_root=$(echo "$boost_root" | sed 's/\\/\//g')
          echo -E "boost_root=$boost_root" >> $GITHUB_OUTPUT

          # Patch boost-root with workspace module
          cp -r "$workspace_root"/corosio-root "libs/$module"

          # Patch boost-root with capy dependency
          cp -r "$workspace_root"/capy-root "libs/capy"

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Build Antora Docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config --global --add safe.directory "$(pwd)"

          BOOST_SRC_DIR="$(pwd)/boost-root"
          export BOOST_SRC_DIR
          cd boost-root/libs/corosio

          cd doc
          # Tee'd purely to keep the build log readable in the step output;
          # Antora exits zero even on failure, which is why the checks below
          # exist.
          set -o pipefail
          bash ./build_antora.sh 2>&1 | tee "$RUNNER_TEMP/antora.log"

          # Antora returns zero even if it fails, so we check if the site directory exists
          if [ ! -d "build/site" ]; then
              echo "Antora build failed"
              exit 1
          fi

      # BLOCKING, but deliberately not a count. A MrDocs without the
      # extension installed ignores the script entirely and renders the
      # reference with no examples while still reporting success, so something
      # has to notice. Checking that one known example reached the HTML catches
      # that without asking anyone to maintain a number: this example exists
      # only in test/doc/reference/socket_option__no_delay.record.cpp, never in
      # a header.
      - name: Doc-quality - reference examples were injected (BLOCKING)
        run: |
          set -euo pipefail
          site=boost-root/libs/corosio/doc/build/site
          if ! grep -rqF disable_nagle_on_a_connected_socket "$site/corosio/reference"; then
            echo "No injected example found in the rendered reference." >&2
            echo "The reference-snippets transform did not run, or its output" >&2
            echo "did not reach the HTML. doc/build_antora.sh installs the" >&2
            echo "extension into a MrDocs and exports MRDOCS_ROOT; check that it" >&2
            echo "did, and that the Antora reference extension accepted it -- it" >&2
            echo "logs 'Using local MrDocs' at debug level, and setting a" >&2
            echo "'version' in doc/local-playbook.yml makes it reject a local" >&2
            echo "install and silently download its own instead." >&2
            exit 1
          fi
          echo "the rendered reference carries its injected examples"

      - name: Create Antora Docs Artifact
        uses: actions/upload-artifact@v4
        with:
          name: antora-docs
          path: boost-root/libs/corosio/doc/build/site