Pushing to prod PR#410 onward

.github/workflows/merge-main-into-staging.yaml

@@ -19,6 +19,7 @@ jobs:
         uses: actions/checkout@v3
         with:
           ref: staging
+          fetch-depth: 0
 
       - name: Configure git
         run: |
@@ -27,8 +28,7 @@ jobs:
 
       - name: Merge in main branch
         run: |
-          git fetch origin main:main
-          git merge main --no-ff --allow-unrelated-histories --strategy-option theirs -m "Merging latest changes from main into staging"
+          git merge --no-ff origin/main
 
       - name: Create pull request
         id: pr-number

README.md

@@ -142,3 +142,5 @@ make get-source
 After you pull in the changes, commit them to this repo as part of the release notes process.
 
 <!-- September 16, 2024: Need to mention rendered Python `.html` docs and generated `.md` test descriptions -->
+
+<!-- Testing simplified merge strategy -->

site/Makefile

@@ -110,10 +110,9 @@ deploy-prod:
 		quarto render --profile production && aws s3 sync ./_site s3://docs-ci-cd-prod/site/ --delete && aws cloudfront create-invalidation --distribution-id E2I9R40IH01NW3 --paths "/*" --no-cli-pager > /dev/null; \
 	fi
 
-# Deployment to https://docs.validmind.ai/
-# TO DO Fix Cloudfront distribution ID
+# Deployment to https://docs-staging.validmind.ai/
 deploy-staging:
-	@if [ "`git rev-parse --abbrev-ref HEAD`" != "nrichers/sc-6277/deploy-staging-docs-site-workflow" ]; then \
+	@if [ "`git rev-parse --abbrev-ref HEAD`" != "staging" ]; then \
 		echo "You're not on the staging branch, no action taken."; \
 	else \
 		echo "\nDeploying staging site ..."; \
@@ -122,4 +121,4 @@ deploy-staging:
 
 # Generate release notes
 release-notes:
-	@python ../release-scripts/generate_release_objects.py
+	@python ../release-scripts/generate_release_objects.py

site/_quarto.yml

@@ -108,6 +108,7 @@ website:
         - text: "---"
         - text: "RELEASES"
         # MAKE-RELEASE-NOTES-EMBED-MARKER
+        - releases/2024-sep-25/release-notes.qmd
         - releases/2024-sep-09/release-notes.qmd
         - releases/2024-aug-13/release-notes.qmd
         - releases/2024-jul-22/release-notes.qmd

site/about/contributing/style-guide/conventions.qmd

@@ -170,14 +170,14 @@ Column 2, 50% wide
   ```
   | Inline links in training | Footnotes in user guides | 
   |------|-----|
-  | ![](training_inline-links.png){fig-alt="A screenshot showing an example of inline links in training materials"} | ![](user-guide_footenotes.png){fig-alt="A screenshot showing an example of margin footnotes in a user guide"} |
+  | ![](training_inline-links.png){fig-alt="A screenshot showing an example of inline links in training materials" class="screenshot"} | ![](user-guide_footenotes.png){fig-alt="A screenshot showing an example of margin footnotes in a user guide" class="screenshot"} |
   : **Inline vs footnotes links** examples {.hover}
 
 Footnotes will automatically appear in the correct location in the margin, regardless of their origin or format.
 
 | Correct | Incorrect | 
 |------|-----|
-| ![](margin-footnotes_correct.png){fig-alt="A screenshot showing a correct example of footnote links automatically placed in the margin"} | ![](inline-links_incorrect.png){fig-alt="A screenshot showing an incorrect example of supplementary links in inline instructional text"} |
+| ![](margin-footnotes_correct.png){fig-alt="A screenshot showing a correct example of footnote links automatically placed in the margin" class="screenshot"} | ![](inline-links_incorrect.png){fig-alt="A screenshot showing an incorrect example of supplementary links in inline instructional text" class="screenshot"} |
 : **Margin footnotes** examples {.hover}
 
 ### Emphasis
@@ -242,6 +242,17 @@ Filenames should generally match the title of the article[^9] or concisely summa
 | `model-lifecycle.gif` | `img4.gif`|
 : **Filenames** examples {.hover}
 
+#### Screenshots
+
+- Screen captures of the UI or other elements to assist users with their tasks should have the `.screenshot` class applied to them, which will add a border distinguishing the image from the rest of the text.
+- When necessary, interactive elements within a larger complex screenshot should be highlighted for ease of comprehension.
+
+| Correct | Incorrect | 
+|------|-----|
+|   ![Verification email sent by ValidMind](/guide/configuration/verify-email.png){width=70% fig-alt="Screenshot of the verification email sent by ValidMind" class="screenshot"}  |  ![](screenshot-incorrect.png){width=90%} | 
+|  `![Verification email sent by ValidMind](/guide/configuration/verify-email.png){width=80% fig-alt="Screenshot of the verification email sent by ValidMind" class="screenshot"}` |  `![](/guide/configuration/verify-email.png){width=80%}`  |
+: **Screenshot** examples {.hover}
+
 #### Code
 - Format code in its own code block.[^10]
 - Declare the code language within the pre-formatted block to properly trigger syntax highlighting.
@@ -324,7 +335,7 @@ The ValidMind Academy is delivered in Revealjs presentation format,[^18] with a
 
   :::: {.flex .flex-wrap .justify-around}
 
-  ::: {.w-50-ns}
+  ::: {.w-40-ns}
 
   Example overlay box:
 
@@ -347,7 +358,7 @@ The ValidMind Academy is delivered in Revealjs presentation format,[^18] with a
 
   ::: {.w-50-ns}
 
-  ![](training-overlay.png){fig-alt="A screenshot showing an example of a training overlay"} 
+  ![](training-overlay.png){fig-alt="A screenshot showing an example of a training overlay" class="screenshot"} 
 
   :::
 

site/developer/model-documentation/work-with-test-results.qmd

@@ -30,7 +30,7 @@ Once generated via the {{< var validmind.developer >}}, view and add the test re
    - Select the tests to insert into the model documentation from the list of available tests.
    - Search by name using **{{<fa magnifying-glass >}} Search** on the top-left.
 
-    ![](test-driven-block-menu.png){width=85% fig-alt="A screenshot showing several test-driven blocks that have been selected for insertion into the model documentation"}
+    ![](test-driven-block-menu.png){width=85% fig-alt="A screenshot showing several test-driven blocks that have been selected for insertion into the model documentation" class="screenshot"}
 
    To preview what is included in a test, select it. By default, selected tests are previewed.
 
@@ -60,7 +60,7 @@ After you have added a test result to your documentation, you can view the follo
     - On the test result timeline, click on the **{{< fa chevron-down >}}** associated with a test run to expand for details.
     - When you are done, you can either click **Cancel** or **{{< fa x >}}** to close the metadata menu.
 
-    ![](test-run-details.gif){width=85% fig-alt="A gif showcasing detail expansion of test runs on the test result timeline"}
+    ![](test-run-details.gif){width=85% fig-alt="A gif showcasing detail expansion of test runs on the test result timeline" class="screenshot"}
 
 
 ## What's next

site/get-started/developer/try-with-colab.qmd

@@ -28,7 +28,7 @@ Google Colaboratory (Colab) is a free Jupyter Notebook environment that runs in
 
 1. Open the QuickStart notebook in Google Colaboratory: [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg){fig-alt="Open in Colab"}](https://colab.research.google.com/drive/1NLtjCFUZV2I_ttGUkiAL9uwGZK_SGUlw?usp=share_link)
 
-   ![](google-colab.png){width=90% fig-alt="The QuickStart notebook opened in Google Colab"}
+   ![](google-colab.png){width=90% fig-alt="The QuickStart notebook opened in Google Colab" class="screenshot"}
 
 2. Click **File** > **Save a copy in Drive** to make a copy of the QuickStart notebook so that you can modify it later.
 

site/get-started/developer/try-with-jupyterhub.qmd

@@ -5,12 +5,6 @@ date: last-modified
 
 Learn how to document a model with ValidMind on JupyterHub.
 
-::: {.grid}
-::: {.g-col-10}
-{{< video https://youtu.be/rIR8Mql7eGs >}}
-:::
-:::
-
 ::: {.prereq}
 
 ## {{< fa star-of-life >}} Before you begin
@@ -29,7 +23,7 @@ Signing up is FREE — {{< var link.register >}}
 
    This link takes you to ValidMind's JupyterHub instance where you can log in with the Auth0 credentials for your ValidMind account to access the QuickStart notebook.
 
-   ![](jupyterhub-dashboard.png){width=90% fig-alt="The QuickStart notebook opened in JupyterHub"}
+   ![](jupyterhub-dashboard.png){width=90% fig-alt="The QuickStart notebook opened in JupyterHub"  class="screenshot"}
 
 <!---
 1. In a web browser, go to <https://jupyterhub.validmind.ai>.
@@ -57,6 +51,12 @@ Signing up is FREE — {{< var link.register >}}
 
 You can now continue running the rest of the cells if you want to see how the demo notebook works or, to save some time, you can move on to the next section to explore the {{< var vm.platform >}}. 
 
+#### Watch this tutorial
+
+Need more help? Experience this guide in video format:
+
+<iframe width="1120" height="630" src="https://www.youtube.com/embed/rIR8Mql7eGs?si=vnZA_zP4tAjFjI4r" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen style="box-shadow: 5px 5px 5px #ccc, -5px 5px 5px #ccc; border-radius: 5px;"></iframe>
+
 <!--- TO DO Screenshot --->
 
 ## What's next

site/get-started/platform/explore-sample-model-documentation.qmd

@@ -7,7 +7,7 @@ First, let's take a look at how the ValidMind handles model documentation. The b
 
 <!-- Using the variable in alt text messes up the image display  -->
 
-![](platform-dashboard.png){width=90% fig-alt="An image showing the ValidMind Platform UI main dashboard"}
+![](platform-dashboard.png){width=90% fig-alt="An image showing the ValidMind Platform UI main dashboard" class="screenshot"}
 
 The {{< var validmind.platform >}} is the central place to: 
 
@@ -34,7 +34,7 @@ Signing up is FREE — {{< var link.register >}}
 
 2. Locate or search for the `[QuickStart] Customer Churn Model` and select it.
 
-   ![](customer-churn-model.png){width=90% fig-alt="An image showing the main page for the QuickStart Customer Churn Model"}
+   ![](customer-churn-model.png){width=90% fig-alt="An image showing the main page for the QuickStart Customer Churn Model" class="screenshot"}
 
    On the model overview page that opens, you can find important information about the model, such as:
 
@@ -53,7 +53,7 @@ Signing up is FREE — {{< var link.register >}}
 
    <!-- Using the variable in alt text messes up the image display  -->
 
-   ![](data-description.png){width=90% fig-align="left" fig-alt="An image showing the data description page in the platform UI"}
+   ![](data-description.png){width=90% fig-align="left" fig-alt="An image showing the data description page in the platform UI" class="screenshot"}
 
    - This content is _generated by the {{< var validmind.developer >}}_ and provides information about the dataset used, including histograms, information about dataset quality, and test results.
    - Sections that need your attention get flagged with `Requires Attention`. These sections get flagged automatically whenever a test result is above or below a certain threshold.

site/get-started/platform/generate-documentation-for-your-model.qmd

@@ -22,7 +22,7 @@ Signing up is FREE — {{< var link.register >}}
 
 1. In the left sidebar, go to the **Getting Started** section of your previously registered model:[^1]
 
-   ![](platform-getting-started.png){width=90% fig-align="left" fig-alt="The QuickStart notebook in Colab with the section showing that you need to replace"}
+   ![](platform-getting-started.png){width=90% fig-align="left" fig-alt="The QuickStart notebook in Colab with the section showing that you need to replace" class="screenshot"}
 
    The page that opens provides you with a _code snippet_ to use with the {{< var validmind.developer >}}, including: 
 
@@ -43,7 +43,7 @@ Signing up is FREE — {{< var link.register >}}
 
 4. In the QuickStart notebook, replace the `vm.init()` lines that look like the following with your own client integration information from the earlier step when you registered your new model:
 
-   ![](jupyterhub-secrets.png){width=60% fig-align="left" fig-alt="The QuickStart notebook in Colab with the section showing that you need to replace"}
+   ![](jupyterhub-secrets.png){width=60% fig-align="left" fig-alt="The QuickStart notebook in Colab with the section showing that you need to replace" class="screenshot"}
 
 5. Run each cell in the notebook:
 

site/get-started/platform/register-your-first-model.qmd

@@ -27,15 +27,15 @@ Signing up is FREE — {{< var link.register >}}
    - Documentation template: `Binary classification`
    - Use case: `Attrition/Churn Management`
 
-   ![](model-registration.png){width=45% fig-alt="The Get Started page for a model that shows the code snippet you need to copy with the Copy snippet to clipboard button"}
+   ![](model-registration.png){width=45% fig-alt="The Get Started page for a model that shows the code snippet you need to copy with the Copy snippet to clipboard button" class="screenshot"}
 
    You can fill in other options according to your own preference. 
 
 2. Click **Continue**.
 
    After the model is registered, you get initial model documentation and a validation report based on the documentation template. 
 
-   ![](platform-first-model.png){width=90% fig-alt="The main page for a model with the Documentation and Validation Report options highlighted in the left sidebar"}
+   ![](platform-first-model.png){width=90% fig-alt="The main page for a model with the Documentation and Validation Report options highlighted in the left sidebar" class="screenshot"}
 
 ## What's next
 

site/guide/configuration/configure-google-private-service-connect.qmd

@@ -86,7 +86,7 @@ Create a private subnet in a supported GCP region that can be used to expose Val
 
 Create a Private Service Connect endpoint for accessing ValidMind services securely and privately, with service discovery managed via Google Cloud’s Service Directory.
 
-![Creating an endpoint in the Google Cloud Console](gcp-add-validmind-endpoint-panel.png){fig-alt="Screenshot of an endpoint being created with the options specified in the steps"}
+![Creating an endpoint in the Google Cloud Console](gcp-add-validmind-endpoint-panel.png){fig-alt="Screenshot of an endpoint being created with the options specified in the steps" class="screenshot"}
 
 ### Steps
 
@@ -119,13 +119,13 @@ Create a Private Service Connect endpoint for accessing ValidMind services secur
 
 After the endpoint is active, test that the service is reachable through the private connection and that DNS requests resolve as expected.
 
-![Active `private` endpoint in the Google Cloud Console](gcp-add-validmind-endpoint.png){fig-alt="Active endpoint being shown in the Google Cloud Console"}
+![Active `private` endpoint in the Google Cloud Console](gcp-add-validmind-endpoint.png){fig-alt="Active endpoint being shown in the Google Cloud Console" class="screenshot"}
 
 ## Create an endpoint to connect to the ValidMind authentication service
 
 Repeat the steps to create an endpoint to connect to ValidMind[^3] to add another endpoint for the ValidMind authentication service.
 
-![Creating an endpoint in the Google Cloud Console](gcp-add-auth-endpoint-panel.png){fig-alt="Screenshot of an endpoint being created with the options specified in the steps"}
+![Creating an endpoint in the Google Cloud Console](gcp-add-auth-endpoint-panel.png){fig-alt="Screenshot of an endpoint being created with the options specified in the steps" class="screenshot"}
 
 ### Steps
 
@@ -140,7 +140,7 @@ Repeat the steps to create an endpoint to connect to ValidMind[^3] to add anothe
 
 After the endpoint is active, test that the service is reachable through the private connection and that DNS requests resolve as expected.
 
-![Active `auth` endpoint in the Google Cloud Console](gcp-add-auth-endpoint.png){fig-alt="Active endpoint being shown in the Google Cloud Console"}
+![Active `auth` endpoint in the Google Cloud Console](gcp-add-auth-endpoint.png){fig-alt="Active endpoint being shown in the Google Cloud Console" class="screenshot"}
 
 ## Test connectivity