synapse/.github/workflows/docs-pr.yaml

name: Prepare documentation PR preview

on:
  pull_request:
    paths:
      - docs/**
      - book.toml
      - .github/workflows/docs-pr.yaml
      - scripts-dev/schema_versions.py
      # If the docs' python dependencies change, rebuild the book and test links.
      - pyproject.toml

jobs:
  pages:
    name: GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        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'

      # Building the book requires running the `scripts-dev/schema_versions.py`
      # script first, which has some python dependencies.
      - name: Setup Poetry
        uses: matrix-org/setup-python-poetry@5bbf6603c5c930615ec8a29f1b5d7d258d905aa4 # v2.0.0
        with:
          install-project: "false"
          groups: "docs"
          poetry-version: "2.4.1"

      - 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: |
          poetry run mdbook build
          cp book/welcome_and_overview.html book/index.html

      - name: Upload Artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

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

      # Building the book requires running the `scripts-dev/schema_versions.py`
      # script first, which has some python dependencies.
      - name: Setup Poetry
        uses: matrix-org/setup-python-poetry@5bbf6603c5c930615ec8a29f1b5d7d258d905aa4 # v2.0.0
        with:
          install-project: "false"
          groups: "docs"
          poetry-version: "2.4.1"

      - 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="./" poetry run 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