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 }}