name: Prepare documentation PR preview

on:
  pull_request:
    paths:
      - docs/**
      - book.toml
      - .github/workflows/docs-pr.yaml
      - scripts-dev/schema_versions.py

jobs:
  pages:
    name: GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          # Fetch all history so that the schema_versions script works.
          fetch-depth: 0

      - name: Setup mdbook
        uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
        with:
          mdbook-version: '0.5.2'

      - name: Setup python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.x"

      - run: "pip install 'packaging>=20.0' 'GitPython>=3.1.20'"

      - name: Build the documentation
        # mdbook will only create an index.html if we're including docs/README.md in SUMMARY.md.
        # However, we're using docs/README.md for other purposes and need to pick a new page
        # as the default. Let's opt for the welcome page instead.
        run: |
          mdbook build
          cp book/welcome_and_overview.html book/index.html

      - name: Upload Artifact
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: book
          path: book
          # We'll only use this in a workflow_run, then we're done with it
          retention-days: 1

  link-check:
    name: Check links in documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup mdbook
        uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
        with:
          mdbook-version: '0.5.2'

      - name: Setup htmltest
        run: |
          wget https://github.com/wjdp/htmltest/releases/download/v0.17.0/htmltest_0.17.0_linux_amd64.tar.gz
          echo '775c597ee74899d6002cd2d93076f897f4ba68686bceabe2e5d72e84c57bc0fb  htmltest_0.17.0_linux_amd64.tar.gz' | sha256sum -c
          tar zxf htmltest_0.17.0_linux_amd64.tar.gz

      - name: Test links with htmltest
        run: |
          # Build the book with `./` as the site URL (to make checks on 404.html possible)
          MDBOOK_OUTPUT__HTML__SITE_URL="./" mdbook build

          # Delete the contents of the print.html file, as it can raise false
          # positives during link checking.
          #
          # We empty out the file, instead of deleting it, as doing so would
          # just cause htmltest to complain that links to it were invalid.
          # Ideally `htmltest` would have an option to ignore specific files
          # instead.
          echo '<!DOCTYPE HTML>' > book/print.html

          ./htmltest book --conf docs/.htmltest.yml
