build-deploy-docs.yml

# This workflow generates the required static content and pushes it automatically to the desired branch
# being used for GitHub Pages. The resulting commit is made by "Unknown" user.
name: build-deploy-docs
# Anytime a commit is pushed to the brach listed below this workflow is triggered
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    # The working directory needs to be set to the same directory that contains the mkdocs.yml file
    defaults:
      run:
        working-directory: ./
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.11
      - name: Install MkDocs and Plugins
        run: LC_ALL=en_US.UTF-8 pip install -r requirements.txt
        #
        # CAUTION !!
        #
        # Proceed with care with this command.
        #
        # The command below is used to deploy the static content to the branch specified by the -b flag.
        # This command is a wrapper for several git commands and is destructive to the specified branch.
        # The 'mkdocs gh-deploy' command deletes all content on the selected branch and generates new
        # content based on the markdown files.
        #
        # Make sure not to edit any files manually on the gh-pages branch as it will cause this workflow to fail
        # and may have unintended consequences.
        #
      - name: Deploy docs to root on gh-pages branch
        run: mkdocs gh-deploy -m "Update GitHub pages for latest documentation release" -b gh-pages --force -v