synapse/.github/workflows/docs.yaml

name: Deploy the documentation

on:
  push:
    branches:
      # For bleeding-edge documentation
      - develop
      # For documentation specific to a release
      - 'release-v*'
      # stable docs
      - master

  workflow_dispatch:

jobs:
  pre:
    name: Calculate variables for GitHub Pages deployment
    runs-on: ubuntu-latest
    steps:
      # Figure out the target directory.
      #
      # The target directory depends on the name of the branch
      #
      - name: Get the target directory name
        id: vars
        run: |
          # first strip the 'refs/heads/' prefix with some shell foo
          branch="${GITHUB_REF#refs/heads/}"

          case $branch in
              release-*)
                  # strip 'release-' from the name for release branches.
                  branch="${branch#release-}"
                  ;;
              master)
                  # deploy to "latest" for the master branch.
                  branch="latest"
                  ;;
          esac

          # finally, set the 'branch-version' var.
          echo "branch-version=$branch" >> "$GITHUB_OUTPUT"          
    outputs:
      branch-version: ${{ steps.vars.outputs.branch-version }}

################################################################################
  pages-docs:
    name: GitHub Pages
    runs-on: ubuntu-latest
    needs:
      - pre
    steps:
      - uses: actions/checkout@v4
        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.4.17'

      - name: Set version of docs
        run: echo 'window.SYNAPSE_VERSION = "${{ needs.pre.outputs.branch-version }}";' > ./docs/website_files/version.js

      - name: Setup python
        uses: actions/setup-python@v5
        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          

      # Deploy to the target directory.
      - name: Deploy to gh pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book
          destination_dir: ./${{ needs.pre.outputs.branch-version }}

################################################################################
  pages-devdocs:
    name: GitHub Pages (developer docs)
    runs-on: ubuntu-latest
    needs:
      - pre
    steps:
      - uses: actions/checkout@v4

      - name: "Set up Sphinx"
        uses: matrix-org/setup-python-poetry@v1
        with:
          python-version: "3.x"
          poetry-version: "1.3.2"
          groups: "dev-docs"
          extras: ""

      - name: Build the documentation
        run: |
          cd dev-docs
          poetry run make html          

      # Deploy to the target directory.
      - name: Deploy to gh pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dev-docs/_build/html
          destination_dir: ./dev-docs/${{ needs.pre.outputs.branch-version }}