add publish docs job to CI (#26245)

This adds a new job to our CI process that will conditionally trigger on
pushes to main. The new job depends on the `make_doc` job finishing, and
then it retrieves the documentation artifact from that job and uploads
it to the website's `main` docs.

It was necessary to include the hidden files when creating the artifact
from the `make_docs` step so that the updated `.htaccess` file would be
included.

Secrets are stored in github and are never exposed in logs etc. 

Tested with bad docs (failed build) and adding new docs. 

Set to use the `--dry-run` option for now. Once we've had a few days of
it in place without issue and confirmed that the updates would be the
same or better than our current update method, I'll remove that flag and
it will begin actually publishing the docs.

[reviewed by @tzinsky - thanks!]

.github/workflows/CI.yml

@@ -53,6 +53,7 @@ jobs:
       with:
         name: documentation
         path: doc/html
+        include-hidden-files: true
 
   make_mason:
     runs-on: ubuntu-latest
@@ -189,3 +190,30 @@ jobs:
               break
             fi
           done
+
+  publish-docs:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs: make_doc
+    steps:
+      - name: download docs
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation
+
+      - name: setup keys
+        run: |
+          install -m 600 -D /dev/null ~/.ssh/id_rsa
+          echo "${{ secrets.WEBSITE_KEY }}" > ~/.ssh/id_rsa
+          echo "${{ secrets.WEBSITE_KNOWN_HOSTS}}" > ~/.ssh/known_hosts
+
+      - name: push docs
+        run: |
+          echo "Publish module docs to web server"
+          # py-modindex.html is not needed
+          rm -f py-modindex.html
+          # Remove all hidden files except .htaccess
+          find . -maxdepth 1 -type f -name ".*" ! -name ".htaccess" -exec rm -f {} +
+          rsync -avz --cvs-exclude --delete --relative --dry-run . ${{ secrets.WEBSITE_USER }}@${{ secrets.WEBSITE_URL }}:${{ secrets.WEBSITE_PATH }}
+          rm ~/.ssh/id_rsa
+          rm ~/.ssh/known_hosts