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*'

  workflow_dispatch:

jobs:
  pages:
    name: GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdbook
        uses: peaceiris/actions-mdbook@4b5ef36b314c2599664ca107bb8c02412548d79d # v1.1.14
        with:
          mdbook-version: '0.4.9'

      - name: Build the documentation
        run: mdbook build

      # Deploy to the latest documentation directories
      - name: Deploy latest documentation
        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          keep_files: true
          publish_dir: ./book
          destination_dir: ./develop

      - name: Get the current Synapse version
        id: vars
        # The $GITHUB_REF value for a branch looks like `refs/heads/release-v1.2`. We do some
        # shell magic to remove the "refs/heads/release-v" bit from this, to end up with "1.2",
        # our major/minor version number, and set this to a var called `branch-version`.
        #
        # We then use some python to get Synapse's full version string, which may look
        # like "1.2.3rc4". We set this to a var called `synapse-version`. We use this
        # to determine if this release is still an RC, and if so block deployment.
        run: |
          echo ::set-output name=branch-version::${GITHUB_REF#refs/heads/release-v}
          echo ::set-output name=synapse-version::`python3 -c 'import synapse; print(synapse.__version__)'`

      # Deploy to the version-specific directory
      - name: Deploy release-specific documentation
        # We only carry out this step if we're running on a release branch,
        # and the current Synapse version does not have "rc" in the name.
        #
        # The result is that only full releases are deployed, but can be
        # updated if the release branch gets retroactive fixes.
        if: ${{ startsWith( github.ref, 'refs/heads/release-v' ) && !contains( steps.vars.outputs.synapse-version, 'rc') }}
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          keep_files: true
          publish_dir: ./book
          # The resulting documentation will end up in a directory named `vX.Y`.
          destination_dir: ./v${{ steps.vars.outputs.branch-version }}