Deploy the documentation #162
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Deploy the documentation | |
| on: | |
| push: | |
| branches: | |
| # For documentation specific to a release | |
| - "famedly-release/v*" | |
| # stable docs | |
| - master | |
| workflow_dispatch: | |
| permissions: | |
| contents: write | |
| 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 | |
| famedly-release/v*) | |
| # strip 'famedly-release/' from the name for release branches. | |
| branch="${branch#famedly-release/v}" | |
| ;; | |
| 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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| with: | |
| # Fetch all history so that the schema_versions script works. | |
| fetch-depth: 0 | |
| - name: Caching | |
| uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0 | |
| with: | |
| shared-key: "mdbook" | |
| save-if: ${{ ! startsWith(github.ref, 'gh-readonly-queue/') }} | |
| - name: Install required tooling | |
| env: | |
| MDBOOK_VERSION: "0.5.2" | |
| run: | | |
| cargo install mdbook-linkcheck mdbook-mermaid | |
| cargo install mdbook --no-default-features --features search --vers "${{ env.MDBOOK_VERSION }}" --locked | |
| - 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@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: Prepare and publish schema files | |
| run: | | |
| sudo apt-get update && sudo apt-get install -y yq | |
| mkdir -p book/schema | |
| # Remove developer notice before publishing. | |
| rm schema/v*/Do\ not\ edit\ files\ in\ this\ folder | |
| # Copy schema files that are independent from current Synapse version. | |
| cp -r -t book/schema schema/v*/ | |
| # Convert config schema from YAML source file to JSON. | |
| yq < schema/synapse-config.schema.yaml \ | |
| > book/schema/synapse-config.schema.json | |
| # Deploy to the target directory without wiping other versions. | |
| # We use a git worktree so we can merge into gh-pages incrementally, | |
| # equivalent to what peaceiris/actions-gh-pages (action used by element/synapse) | |
| # does with destination_dir. | |
| - name: Deploy to gh-pages | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| VERSION="${{ needs.pre.outputs.branch-version }}" | |
| # Set up a worktree pointing at the gh-pages branch (create it if absent). | |
| git fetch origin gh-pages || true | |
| if git show-ref --verify --quiet refs/remotes/origin/gh-pages; then | |
| git worktree add gh-pages-dir origin/gh-pages | |
| else | |
| git worktree add --orphan -b gh-pages gh-pages-dir | |
| fi | |
| # Replace only this version's directory, preserving all others. | |
| rm -rf "gh-pages-dir/$VERSION" | |
| mkdir -p "gh-pages-dir/$VERSION" | |
| cp -r book/. "gh-pages-dir/$VERSION/" | |
| # Ensure a root redirect to latest exists. | |
| if [ ! -f gh-pages-dir/index.html ]; then | |
| echo '<!DOCTYPE html><meta http-equiv="refresh" content="0; url=latest/index.html">' \ | |
| > gh-pages-dir/index.html | |
| fi | |
| cd gh-pages-dir | |
| git add . | |
| git diff --staged --quiet || git commit -m "docs: deploy $VERSION" | |
| git push origin HEAD:gh-pages |