documentation.yaml

name: Documentation check

on: [pull_request]

permissions:
  contents: write

jobs:
  docs-checks:
    name: ${{ matrix.doc-type }}
    strategy:
      # Let every format report. Without this, one failing format cancels
      # the other two, and a build that fails partway through the examples
      # takes the evidence of the others with it.
      fail-fast: false
      matrix:
        doc-type: [html, latex, epub]

    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@main
    - name: Set up Python
      uses: actions/setup-python@main
      with:
        python-version: '3.10'
    - name: Setup Linux Environment
      run: |
        sudo apt-get install libglu1
    - name: Install docs dependencies
      run: |
        python -m pip install -r docs/requirements.txt
    - name: Install package
      run: |
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
        pip install -e .
    - name: Check the example digest is current
      run: python docs/example_digest.py --check

    - name: Build ${{ matrix.doc-type }} documentation
      run: sphinx-build -Wnb ${{ matrix.doc-type }} docs/source/ docs/build-${{ matrix.doc-type }}/

    # Read the Docs stops a build at fifteen minutes and the examples take
    # about twenty, so it restores what the examples produced here instead
    # of running them. The archive is named by the digest of the example
    # inputs and of the library, and Read the Docs only restores one whose
    # digest matches the commit it is building.
    - name: Publish the example cache
      if: matrix.doc-type == 'html' && github.event.pull_request.head.repo.full_name == github.repository
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        name=$(python docs/example_cache.py name)
        python docs/example_cache.py pack "$name"
        gh release view docs-cache >/dev/null 2>&1 \
          || gh release create docs-cache --title "Documentation example cache" \
               --notes "Figures the documentation examples produce, named by the digest from docs/example_digest.py. Read the Docs restores the archive matching the commit it builds. Managed by the documentation workflow." \
               --latest=false
        gh release upload docs-cache "$name" --clobber

    # A pull request that changes an example has no cache for its new
    # digest until the step above finishes, so the Read the Docs build
    # that started alongside this job ran the examples and timed out.
    # Build it again now that the archive is published, and it is warm.
    #
    # Needs a READTHEDOCS_TOKEN secret, from Settings -> API Tokens on
    # Read the Docs. Without it this step says so and does nothing, and
    # the only cost is having to press Rebuild by hand.
    - name: Rebuild the docs on Read the Docs
      if: matrix.doc-type == 'html' && github.event.pull_request.head.repo.full_name == github.repository
      env:
        RTD_TOKEN: ${{ secrets.READTHEDOCS_TOKEN }}
        RTD_VERSION: ${{ github.event.pull_request.number }}
      run: |
        if [ -z "$RTD_TOKEN" ]; then
          echo "No READTHEDOCS_TOKEN secret, skipping the rebuild."
          echo "Press Rebuild on the Read the Docs build to pick up the cache."
          exit 0
        fi
        # A pull request build is a version named after the pull request.
        code=$(curl -sS -o /tmp/rtd.json -w '%{http_code}' -X POST \
          -H "Authorization: Token $RTD_TOKEN" \
          "https://app.readthedocs.org/api/v3/projects/microstructpy/versions/$RTD_VERSION/builds/")
        echo "Read the Docs answered $code"
        cat /tmp/rtd.json
        case "$code" in
          202) echo "Rebuild triggered." ;;
          *) echo "Could not trigger a rebuild. The cache is published, so a"
             echo "rebuild by hand will be warm."; exit 0 ;;
        esac


    - name: Prepare documentation artifact
      run: |
        # Define Path to Upload
        if [ "${{ matrix.doc-type }}" = html ]; then echo "art_path=docs/build-html" >> $GITHUB_ENV; fi
        if [ "${{ matrix.doc-type }}" = latex ]; then echo "art_path=docs/build-latex/MicroStructPy.pdf" >> $GITHUB_ENV; fi
        if [ "${{ matrix.doc-type }}" = epub ]; then echo "art_path=docs/build-epub/MicroStructPy.epub" >> $GITHUB_ENV; fi

    - name: Build PDF (latex only)
      if: matrix.doc-type == 'latex'
      run: |
        # Update apt
        sudo apt-get update
        
        # Install LaTeX packages
        # Recommended by Sphinx on their docs page:
        # https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder
        sudo apt install texlive-latex-recommended
        sudo apt install texlive-fonts-recommended
        sudo apt install tex-gyre # (if latex_engine left to default)
        sudo apt install texlive-latex-extra
        sudo apt install latexmk

        # Make
        cd docs/build-latex
        make
        cd -
        
    - name: Upload artifact
      uses: actions/upload-artifact@main
      with:
        name: microstructpy_${{ matrix.doc-type }}_documentation
        path: ${{ env.art_path }}