build_docs.yml

name: Build Documentation

# Build documentation on:
# - pushes to master and uploads to latest folder
# - Released and uploads to folder that matches release tag
on:
  push:
    branches:
      - master
      - 'releases/**'
  pull_request:
    branches:
      - '*'
  release:
    types:
      - published
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
  cancel-in-progress: true

jobs:
  cpp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: cachix/install-nix-action@v18
      - name: Build docs
        run: nix build --print-build-logs .#vw-cpp-docs
      - name: Upload built docs
        uses: actions/upload-artifact@v4
        with:
          name: cxx_docs
          path: result/html/
  dump-options-build:
    container:
      image: vowpalwabbit/ubuntu1804-build:latest
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
        with:
          submodules: recursive
      - run: |
          sudo apt update
          sudo apt install -y ninja-build
      - name: Configure
        run: cmake -S . -B build -G Ninja -DBUILD_TESTING=OFF
      - name: Build dump options
        run: cmake --build build -t vw-dump-options
      - name: Upload vw-dump-options
        uses: actions/upload-artifact@v4
        with:
          name: vw-dump-options
          path: build/utl/dump_options/vw-dump-options
  python-build:
    container:
      image: vowpalwabbit/manylinux2010-build:latest
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
        with:
          submodules: recursive
      - run: echo "/opt/python/cp310-cp310/bin" >> $GITHUB_PATH
      - name: Build wheel
        shell: bash
        run: |
          pip wheel . -w wheel_output/ --global-option --cmake-options="-DSTATIC_LINK_VW_JAVA=On;-DPython_INCLUDE_DIR='/opt/python/cp310-cp310/include/python3.10/'" --verbose
          auditwheel repair wheel_output/*whl -w audit_output/
      - name: Upload built wheel
        uses: actions/upload-artifact@v4
        with:
          name: python_wheel
          path: audit_output/
  python-doc:
    needs: [python-build, dump-options-build]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
        with:
          submodules: recursive
      - uses: actions/setup-node@v3
      - uses: actions/setup-python@v3
        with:
          python-version: '3.10'
      - name: If this is a push build then set version to latest
        if: ${{ github.event_name == 'push' }}
        run: echo "VW_SPHINX_VERSION_OVERRIDE=latest" >> $GITHUB_ENV
      - name: Download Wheel
        uses: actions/download-artifact@v1
        with:
          name: python_wheel
      - name: Download vw-dump-options
        uses: actions/download-artifact@v1
        with:
          name: vw-dump-options
      - name: Change permissions to rvw-dump-options
        shell: bash
        run: chmod +x ./vw-dump-options/vw-dump-options
      - name: Install dependencies
        shell: bash
        run: |
          pip install -r python/docs/build-requirements.txt
          pip install -r requirements.txt
          pip install PyYAML
          npm install -g handlebars
      - name: Install wheel
        shell: bash
        run: |
          export wheel_files=(python_wheel/*)
          export wheel_file="${wheel_files[0]}"
          echo Installing ${wheel_file}...
          pip install ${wheel_file}
      - name: Generate CLI docs
        run: |
          cd python/docs/cmd_options_template
          python generate_cmdline_docs.py --dump-options-bin ../../../vw-dump-options/vw-dump-options --template ./command_line_args.hbs --out ../source/ --extra-info ./cmdline_help_overrides.yml
      - name: Build docs
        run: |
          cd python/docs
          make html
      - name: Upload built docs
        uses: actions/upload-artifact@v4
        with:
          name: python_docs
          path: python/docs/build/
  upload:
    needs: [cpp, python-doc]
    runs-on: ubuntu-latest
    # The upload step should only be run on the main repository and only for pushes or releases (not pull requests).
    if: ${{ github.repository == 'VowpalWabbit/vowpal_wabbit' && (github.event_name == 'push' || github.event_name == 'release' || github.event_name == 'workflow_dispatch') }}
    steps:
      - name: Set folder name to latest if push
        if: ${{ github.event_name == 'push' }}
        run: echo "FOLDER_NAME=latest" >> $GITHUB_ENV
      - name: Set folder name to version if release
        if: ${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' }}
        run: echo "FOLDER_NAME=$(echo ${GITHUB_REF:10})" >> $GITHUB_ENV
      - name: Download c++ Docs
        uses: actions/download-artifact@v1
        with:
          name: cxx_docs
      - name: Download Python Docs
        uses: actions/download-artifact@v1
        with:
          name: python_docs
      - name: Print contents of directory
        shell: bash
        run: |
          pwd
          ls
          echo $GITHUB_WORKSPACE
      - uses: actions/checkout@v1
        with:
          submodules: recursive
          repository: VowpalWabbit/docs
          ref: master
          # For some reason, path is relative to the directory above GITHUB_WORKSPACE
          # To ensure the rest of the script makes sense, we need to place this under vowpal_wabbit
          path: vowpal_wabbit/docs
      - name: Print contents of directory
        shell: bash
        run: |
          echo $GITHUB_WORKSPACE
          pwd
          ls
          cd docs
          pwd
          ls
      - name: Copy c++ Docs
        shell: bash
        run: |
          rm -rf docs/vowpal_wabbit/cpp/$FOLDER_NAME/
          mkdir -p docs/vowpal_wabbit/cpp/$FOLDER_NAME/
          cp -r cxx_docs/* docs/vowpal_wabbit/cpp/$FOLDER_NAME/
      - name: Copy Python Docs
        shell: bash
        run: |
          rm -rf docs/vowpal_wabbit/python/$FOLDER_NAME/
          mkdir -p docs/vowpal_wabbit/python/$FOLDER_NAME/
          cp -r python_docs/html/* docs/vowpal_wabbit/python/$FOLDER_NAME/
      - name: Checkout master
        shell: bash
        run: |
          cd docs
          git checkout master
      - name: Commit changes
        shell: bash
        run: |
          cd docs
          git add --all
          git config --local user.email "WoboWabbit@hunch.net"
          git config --local user.name "WoboWabbit"
          git commit -m "Update documentation for commit: VowpalWabbit/vowpal_wabbit@${{ github.sha }}"
      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          repository: VowpalWabbit/docs
          directory: docs
          github_token: ${{ secrets.automation_github_token }}