doc-build.yml

name: Build documentation

on:
  pull_request:
  merge_group:
  push:
    branches:
      - master
      - develop
  workflow_dispatch:
    # Allow to run manually

concurrency:
  # Cancel previous runs of this workflow for the same branch
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  get_ci_fixes:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        id: checkout
        uses: actions/checkout@v4
      - name: Merge CI fixes from sagemath/sage
        run: |
          .ci/merge-fixes.sh
        env:
          GH_TOKEN: ${{ github.token }}
          SAGE_CI_FIXES_FROM_REPOSITORIES: ${{ vars.SAGE_CI_FIXES_FROM_REPOSITORIES }}
      - name: Store CI fixes in upstream artifact
        run: |
          mkdir -p upstream
          if git format-patch --stdout test_base > ci_fixes.patch; then
            cp ci_fixes.patch upstream/
          fi
      - uses: actions/upload-artifact@v3
        with:
          path: upstream
          name: upstream

  build-docs:
    runs-on: ubuntu-latest
    container: ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets:dev
    needs: [get_ci_fixes]
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Update system packages
        run: |
          apt-get update && apt-get install -y git zip

      - name: Add prebuilt tree as a worktree
        id: worktree
        run: |
          git config --global --add safe.directory $(pwd)
          git config --global user.email "ci-sage@example.com"
          git config --global user.name "Build & Test workflow"
          # mathjax path in old doc
          mathjax_path_from=$(SAGE_USE_CDNS=no /sage/sage -python -c "from sage_docbuild.conf import mathjax_path; print(mathjax_path)")
          .ci/retrofit-worktree.sh worktree-image /sage
          # mathjax path in new doc
          mathjax_path_to=$(SAGE_USE_CDNS=yes /sage/sage -python -c "from sage_docbuild.conf import mathjax_path; print(mathjax_path)")
          new_version=$(cat src/VERSION.txt)
          # Wipe out chronic diffs between old doc and new doc
          (cd /sage/local/share/doc/sage/html && \
           find . -name "*.html" | xargs sed -i -e '/class="sidebar-brand-text"/ s/Sage [0-9a-z.]* /Sage '"$new_version"' /' \
                                                -e 's;'"$mathjax_path_from"';'"$mathjax_path_to"';' \
                                                -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d')
          # Create git repo from old doc
          DOC_DIR=/sage/local/share/doc/sage/html
          (cd $DOC_DIR && git init && \
           (echo "*.svg binary"; echo "*.pdf binary") >> .gitattributes && \
           (echo ".buildinfo"; echo '*.inv'; echo '.git*'; echo '*.svg'; echo '*.pdf'; echo '*.png'; echo 'searchindex.js') > .gitignore; \
           git add -A && git commit --quiet -m "old")

      - name: Download upstream artifact
        uses: actions/download-artifact@v3
        with:
          path: upstream
          name: upstream

      - name: Apply CI fixes from sagemath/sage
        # After applying the fixes, make sure all changes are marked as uncommitted changes.
        run: |
          if [ -r upstream/ci_fixes.patch ]; then
            (cd worktree-image && git commit -q -m "current changes" --allow-empty -a && git am; git reset --quiet old; git add -N .) < upstream/ci_fixes.patch
          fi

      - name: Incremental build
        id: incremental
        run: |
          # Now re-bootstrap and build. The build is incremental because we were careful with the timestamps.
          ./bootstrap && make sagemath_doc_html-build-deps
        working-directory: ./worktree-image
        env:
          MAKE: make -j2 --output-sync=recurse
          SAGE_NUM_THREADS: 2

      - name: Build (fallback to non-incremental)
        id: build
        if: (success() || failure()) && steps.worktree.outcome == 'success' && steps.incremental.outcome != 'success'
        run: |
          set -ex
          make sagelib-clean && git clean -fx src/sage && ./config.status && make sagemath_doc_html-build-deps
        working-directory: ./worktree-image
        env:
          MAKE: make -j2 --output-sync=recurse
          SAGE_NUM_THREADS: 2

      - name: Build docs
        id: docbuild
        if: (success() || failure()) && (steps.incremental.outcome == 'success' || steps.build.outcome == 'success')
        # Always non-incremental because of the concern that
        # incremental docbuild may introduce broken links (inter-file references) though build succeeds
        run: |
          set -ex
          DOC_DIR=/sage/local/share/doc/sage/html
          mv $DOC_DIR/.git /sage/.git-doc
          make doc-clean doc-uninstall
          mkdir -p $DOC_DIR/ && mv /sage/.git-doc $DOC_DIR/.git
          export SAGE_USE_CDNS=yes
          ./config.status && make sagemath_doc_html-no-deps
        working-directory: ./worktree-image
        env:
          MAKE: make -j2 --output-sync=recurse
          SAGE_NUM_THREADS: 2

      - name: Copy docs
        id: copy
        if: (success() || failure()) && steps.docbuild.outcome == 'success'
        run: |
          set -ex
          DOC_DIR=/sage/local/share/doc/sage/html
          (cd $DOC_DIR && git commit -a -m 'new')
          ls -l /sage/venv/bin
          PATH=/sage/venv/bin:$PATH .ci/create-changes-html.sh $(cd $DOC_DIR; git rev-parse HEAD^) $DOC_DIR
          (cd $DOC_DIR && rm -rf .git)
          # We copy everything to a local folder
          # We also need to replace the symlinks because netlify is not following them
          mkdir -p ./docs
          mv CHANGES.html ./docs
          cp -r -L $DOC_DIR ./docs
          cp  $DOC_DIR/../index.html ./docs
          # Zip everything for increased performance
          zip -r docs.zip docs

      - name: Upload docs
        if: (success() || failure()) && steps.copy.outcome == 'success'
        uses: actions/upload-artifact@v3
        with:
          name: docs
          path: docs.zip

      - name: Build live doc
        id: buildlivedoc
        if: (success() || failure()) && steps.copy.outcome == 'success' && github.repository == 'sagemath/sage' && github.ref == 'refs/heads/develop'
        run: |
          set -ex
          export PATH="build/bin:$PATH"
          eval $(sage-print-system-package-command auto update)
          eval $(sage-print-system-package-command auto --yes --no-install-recommends install zip)
          eval $(sage-print-system-package-command auto --spkg --yes --no-install-recommends install git texlive texlive_luatex free_fonts xindy)
          export SAGE_USE_CDNS=yes
          export SAGE_LIVE_DOC=yes
          export SAGE_JUPYTER_SERVER=binder:sagemath/sage-binder-env/dev
          make doc-clean doc-uninstall
          ./config.status && make sagemath_doc_html-no-deps sagemath_doc_pdf-no-deps
        working-directory: ./worktree-image
        env:
          MAKE: make -j2 --output-sync=recurse
          SAGE_NUM_THREADS: 2

      - name: Copy live doc
        id: copylivedoc
        if: (success() || failure()) && steps.buildlivedoc.outcome == 'success'
        run: |
          set -ex
          mkdir -p ./livedoc
          cp -r -L /sage/local/share/doc/sage/html ./livedoc
          cp -r -L /sage/local/share/doc/sage/pdf ./livedoc
          cp  /sage/local/share/doc/sage/index.html ./livedoc
          zip -r livedoc.zip livedoc

      - name: Upload live doc
        if: (success() || failure()) && steps.copylivedoc.outcome == 'success'
        uses: actions/upload-artifact@v3
        with:
          name: livedoc
          path: livedoc.zip