deploy-docs.yml

name: Build and Deploy Documentation

on:
  push:
    branches:
      - master
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 60

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            scons \
            python3-markdown \
            python3-sphinx \
            python3-numpy \
            python3-scipy \
            libboost-python-dev \
            libboost-numpy-dev \
            libboost-random-dev \
            libboost-iostreams-dev \
            libnetcdf-dev libnetcdf-c++4-dev \
            libsilo-dev \
            libhdf5-serial-dev \
            libsuitesparse-dev \
            g++ \
            gfortran \
            git \
            texlive-latex-base \
            texlive-latex-extra \
            texlive-fonts-recommended

      - name: Install Python dependencies
        run: |
          python -m pip install --upgrade pip
          pip install sphinx markdown numpy scipy

      - name: Verify LaTeX installation
        run: |
          which pdflatex
          pdflatex --version

      - name: Configure build options
        run: |
          # Detect Python version
          PYVER=$(python3 -c "import sys; print(f'{sys.version_info.major}{sys.version_info.minor}')")
          echo "Python version: $PYVER"

          # Detect actual boost library names
          echo "=== Detecting boost libraries ==="
          ls -la /usr/lib/x86_64-linux-gnu/libboost_python* || true
          ls -la /usr/lib/x86_64-linux-gnu/libboost_numpy* || true

          # Try to find the correct boost library suffix
          if [ -f "/usr/lib/x86_64-linux-gnu/libboost_python${PYVER}.so" ]; then
            BOOST_PY_SUFFIX="${PYVER}"
          elif [ -f "/usr/lib/x86_64-linux-gnu/libboost_python3.so" ]; then
            BOOST_PY_SUFFIX="3"
          else
            # Try to auto-detect from available files
            BOOST_PY_SUFFIX=$(ls /usr/lib/x86_64-linux-gnu/libboost_python*.so 2>/dev/null | head -1 | sed 's/.*libboost_python\([^.]*\)\.so/\1/')
          fi

          echo "Detected boost Python suffix: $BOOST_PY_SUFFIX"

          # Add boost_libs to the options file based on detected libraries
          echo "" >> scons/github_ubuntu_options.py
          echo "# Dynamic configuration based on detected boost libraries" >> scons/github_ubuntu_options.py
          echo "boost_libs = ['boost_python${BOOST_PY_SUFFIX}', 'boost_numpy${BOOST_PY_SUFFIX}', 'boost_random', 'boost_iostreams']" >> scons/github_ubuntu_options.py
          echo "" >> scons/github_ubuntu_options.py
          echo "# Compression support" >> scons/github_ubuntu_options.py
          echo "compression_libs = ['boost_iostreams', 'z', 'bz2']" >> scons/github_ubuntu_options.py

          echo "=== Build options file ==="
          cat scons/github_ubuntu_options.py

      - name: Build and install esys-escript
        run: |
          # Build and install esys-escript (default target includes install)
          scons -j2 options_file=scons/github_ubuntu_options.py 2>&1 | tee build.log

          # Check if build succeeded
          if [ ${PIPESTATUS[0]} -ne 0 ]; then
            echo "Build failed! Last 50 lines:"
            tail -50 build.log
            exit 1
          fi

          echo "=== Build completed successfully ==="
          echo "=== Checking esys directory ==="
          ls -la esys/ || echo "esys/ not found"
          ls -la esys/escript/ || echo "esys/escript/ not found"

      - name: Verify esys-escript installation
        run: |
          # Set up environment
          export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH}"
          export LD_LIBRARY_PATH="${GITHUB_WORKSPACE}/lib/esys:${GITHUB_WORKSPACE}/esys.trilinos/lib:/usr/lib/x86_64-linux-gnu/hdf5/serial:/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"

          echo "=== Environment ==="
          echo "PYTHONPATH=$PYTHONPATH"
          echo "LD_LIBRARY_PATH=$LD_LIBRARY_PATH"

          echo "=== Testing esys module import ==="
          python3 -c "import esys.escript; print('esys.escript imported successfully')"

          echo "=== Listing installed modules ==="
          ls -la esys/

      - name: Build documentation
        run: |
          # Set up environment
          export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH}"
          export LD_LIBRARY_PATH="${GITHUB_WORKSPACE}/lib/esys:${GITHUB_WORKSPACE}/esys.trilinos/lib:/usr/lib/x86_64-linux-gnu/hdf5/serial:/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"

          # Build all documentation - show full output
          echo "=== Building documentation ==="
          scons -j2 options_file=scons/github_ubuntu_options.py docs 2>&1 | tee docs.log

          # Check if docs build succeeded
          if [ ${PIPESTATUS[0]} -ne 0 ]; then
            echo "Documentation build failed! Last 100 lines:"
            tail -100 docs.log
            exit 1
          fi

          # Verify Sphinx documentation was built
          echo "=== Verifying Sphinx API documentation ==="
          if [ -d "release/doc/sphinx_api" ] && [ -f "release/doc/sphinx_api/index.html" ]; then
            echo "Sphinx API documentation built successfully"
            ls -lh release/doc/sphinx_api/*.html | head -10
            du -sh release/doc/sphinx_api
          else
            echo "ERROR: Sphinx API documentation not found!"
            echo "Contents of release/doc/:"
            ls -la release/doc/ || echo "release/doc/ does not exist"
            echo "Contents of release/doc/sphinx_api/:"
            ls -la release/doc/sphinx_api/ || echo "release/doc/sphinx_api/ does not exist"
            exit 1
          fi

      - name: Build complete documentation
        run: |
          # Build markdown documentation
          mkdir -p docs

          # Add .nojekyll FIRST to disable Jekyll
          touch docs/.nojekyll

          # Build HTML files
          python3 doc/md2html.py readme README.md docs/index.html
          python3 doc/md2html.py installation installation.md docs/installation.html
          python3 doc/md2html.py options scons/templates/options.md docs/options.html

          # Copy full Sphinx API documentation
          if [ -d "release/doc/sphinx_api" ]; then
            cp -r release/doc/sphinx_api docs/
            echo "Copied full Sphinx API documentation"

            # Verify genindex.html was copied
            if [ -f "docs/sphinx_api/genindex.html" ]; then
              echo "genindex.html copied successfully ($(du -h docs/sphinx_api/genindex.html | cut -f1))"
            else
              echo "WARNING: genindex.html not found in docs/sphinx_api/"
            fi
          else
            # Fallback: copy static assets only
            mkdir -p docs/sphinx_api/_static
            cp -r doc/sphinx_api/_static_built/* docs/sphinx_api/_static/
            cat > docs/sphinx_api/index.html << 'EOF'
          <!DOCTYPE html>
          <html>
          <head>
            <title>API Documentation - Build Required</title>
            <meta http-equiv="refresh" content="0; url=../index.html">
          </head>
          <body>
            <p>Full API documentation requires building esys-escript. Redirecting to <a href="../index.html">main documentation</a>...</p>
          </body>
          </html>
          EOF
            echo "Warning: Sphinx API docs not found, using placeholder"
          fi

          # Copy example archives if available
          if [ -f "release/doc/escript_examples.zip" ]; then
            cp release/doc/escript_examples.zip docs/
            echo "Copied example ZIP archive"
          fi
          if [ -f "release/doc/escript_examples.tar.gz" ]; then
            cp release/doc/escript_examples.tar.gz docs/
            echo "Copied example TAR.GZ archive"
          fi

          # Copy user guide PDF if available
          mkdir -p docs/user
          if [ -f "release/doc/user/user.pdf" ]; then
            cp release/doc/user/user.pdf docs/user/
            echo "Copied user guide PDF"
          else
            # Create placeholder page for user guide
            cat > docs/user/user.pdf.html << 'EOF'
          <!DOCTYPE html>
          <html>
          <head>
            <title>User Guide PDF - Not Available</title>
            <meta http-equiv="refresh" content="5; url=../index.html">
          </head>
          <body>
            <h1>User Guide PDF Not Available</h1>
            <p>The user guide PDF requires LaTeX compilation which is not available in this automated build.</p>
            <p>Please refer to the <a href="../sphinx_api/index.html">Python API documentation</a> instead.</p>
            <p>Redirecting to <a href="../index.html">main documentation</a> in 5 seconds...</p>
          </body>
          </html>
          EOF
            echo "Warning: User guide PDF not found, created placeholder"
          fi

          # Add robots.txt
          echo "User-agent: *" > docs/robots.txt
          echo "Allow: /" >> docs/robots.txt

          # List what we created for debugging
          echo "=== Documentation structure ==="
          find docs -type f | head -40
          echo "Documentation built successfully"

      - name: Configure Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4