Document manual website regeneration/deployment via GitHub Actions

.github/workflows/assemble-website.yml

@@ -4,8 +4,14 @@ name: Assemble website
 
 on:
   # Run this workflow whenever someone opens or adds commits to a PR whose base branch is `main`.
-  # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
-  pull_request: { branches: [ main ] }
+  #
+  # References:
+  # - https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+  # - https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#example-excluding-paths
+  #
+  pull_request:
+    branches: [ main ]
+    paths-ignore: [ '.gitignore', 'README.md', 'development.md', 'docker-compose.yml' ]
   # Allow this workflow to be run manually (e.g., via the "Actions" tab on GitHub).
   # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
   workflow_dispatch: { }

.github/workflows/deploy-to-gh-pages.yml

@@ -4,8 +4,14 @@ name: Deploy to GitHub Pages
 
 on:
   # Run this workflow whenever someone pushes commits or tags to the `main` branch.
-  # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push
-  push: { branches: [ main ] }
+  #
+  # Reference:
+  # - https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push
+  # - https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#example-excluding-paths
+  #
+  push:
+    branches: [ main ]
+    paths-ignore: [ '.gitignore', 'README.md', 'development.md', 'docker-compose.yml' ]
   # Allow this workflow to be run manually (e.g., via the "Actions" tab on GitHub).
   # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
   workflow_dispatch: { }

README.md

@@ -104,6 +104,11 @@ flowchart BT
 The website will automatically be regenerated and redeployed whenever a new commit is made on—or merged into—the `main`
 branch of _this_ repository. Regeneration includes pulling content from the remote repositories. The regeneration and redeployment process usually takes about three minutes to complete.
 
+This repository does _not_ automatically "see" changes made to remote repositories. In other words,
+making a change to one of the upstream repositories will not cause the website to be regenerated and
+redeployed. To regenerate and redeploy the website in that situation, you can follow the instructions
+in the "Deployment" section of the "[Development](./development.md#deployment)" guide.
+
 ## The Home section
 
 The `content/home/` directory contains the source files for the Home section of the website. That directory began as an

development.md

@@ -18,6 +18,8 @@ as opposed to the content aspect.
       * [Runtime section](#runtime-section)
       * [Workflow docs](#workflow-docs)
   * [Deployment](#deployment)
+    * [Automatic deployment](#automatic-deployment)
+    * [Manual deployment](#manual-deployment)
   * [Google Analytics](#google-analytics)
 <!-- TOC -->
 
@@ -100,6 +102,26 @@ The `.github/workflows` directory contains YAML files that we use to configure G
 We use GitHub Actions to (a) compile local and remote content into a single website,
 and to (b) publish that single website to GitHub Pages.
 
+### Automatic deployment
+
+Whenever a commit is added to the `main` branch of this repository, the website will be regenerated
+and redeployed. That happens via the "Deploy to GitHub Pages" GitHub Actions workflow, which is
+specified in: `.github/workflows/deploy-to-gh-pages.yml`
+
+### Manual deployment
+
+If you want to regenerate and redeploy the website without adding a commit to the `main` branch of
+this repository, you can do so by following the steps below:
+
+1. Open the repository's **[Actions](https://github.com/microbiomedata/docs/actions)** tab
+2. In the left sidebar, click the GHA workflow named **Deploy to GitHub Pages**
+3. In the upper right corner, click the **Run workflow** button
+4. In the **Use workflow from** menu that appears, ensure `main` is selected (that's the default)
+5. Click the green **Run workflow** button, which will run the GHA workflow
+6. Click on the new GHA workflow run and wait for the **Assemble website** and
+   **Deploy website** jobs to finish successfully (i.e. to have a green checkmark)
+7. Wait approximately 3 minutes, then visit the website and confirm it shows what you expect
+
 ## Google Analytics
 
 We use Google Analytics to collect and analyze website traffic. You can search the repository for