docs: Explains execution time (#1475)

Fixes #1463 

### Changes
- Explains execution time
- Adds style guide section about adding a badge for paid features
- Updates config for mkdocs-material 9.5, materialx emoji support is
being removed.
- Adds better tooltips, a cool feature that also got released with
mkdocs-material 9.5
- Adds search suggestions

### Caveats
- [mkdocs 1.5 has improved the way they handle link
validation](https://www.mkdocs.org/about/release-notes/#expanded-validation-of-links).
Looks like way I've gone about linking things could be improved, and it
will give a bunch of warnings as a result. The site still builds fine,
but I'm going to fix this in a different PR so this one doesn't take as
much effort to review :)

EDIT: Here's that PR
https://github.com/webrecorder/browsertrix-cloud/pull/1476

### Testing
- Make sure you are up to date with `pip install --upgrade
mkdocs-material`

### Screenshot

**Badge!**
<img width="884" alt="Screenshot 2024-01-17 at 11 59 00 PM"
src="https://github.com/webrecorder/browsertrix-cloud/assets/5672810/62a51cf6-24bd-49f1-a6d0-d335f730bfbe">


### Future
- Should mkdocs-material be versioned in our deployment script? We risk
things breaking if I don't get to them fast enough! 🙃

---------

Co-authored-by: Tessa Walsh <tessa@bitarchivist.net>

docs/develop/docs.md

@@ -129,6 +129,16 @@ For in-line code blocks, syntax highlighting should be added for all code-relate
 
 Renders to: `#!python range()`
 
+### Paid features
+
+`Paid Feature`{ .badge-green }
+
+Some features of Browsertrix Cloud only pertain to those paying for the software on a hosted plan. Denote these with the following:
+
+```markdown
+`Paid Feature`{ .badge-green }
+```
+
 ### Admonitions
 
 We use [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) in their collapsed state to offer additional context or tips that aren't relevant to all users reading the section. We use standard un-collapsible ones when we need to call attention to a specific point.

docs/stylesheets/extra.css

@@ -108,6 +108,14 @@ code {
     font-weight: 600;
 }
 
+.badge-green {
+    background-color: hsl(142 76% 36%) !important;
+    border-color: hsl(142 76% 36%) !important;
+    color: white !important;
+    font-family: var(--md-text-font);
+    font-weight: 600;
+}
+
 .badge-orange {
     background-color: var(--wr-orange-primary) !important;
     border-color: var(--wr-orange-primary) !important;

docs/user-guide/overview.md

@@ -12,9 +12,16 @@ For all organizations the storage panel displays the total number of archived it
 
 ## Crawling
 
+The crawling panel lists the number of currently running and waiting crawls, as well as the total number of pages captured.
+
+### Execution Time
+
+`Paid Feature`{.badge-green}
+
 For organizations with a set execution minute limit, the crawling panel displays a graph of how much execution time has been used and how much is currently remaining. Monthly execution time limits reset on the first of each month at 12:00 AM GMT.
 
-The crawling panel also lists the number of currently running and waiting crawls, as well as the total number of pages captured.
+??? Question "How is execution time calculated?"
+    Execution time is the total runtime of all [_Crawler Instances_](../workflow-setup/#crawler-instances) during a crawl. For instance, if _Crawler Instances_ scale is set to 2× and each crawler instance uses 2 minutes of active crawling time, execution time for the crawl will be 4 minutes. Like elapsed time, this is tracked as the crawl runs so changing the _Crawler Instances_ scale while a crawl is running may change the amount of execution time used in a given time period.
 
 ## Collections
 

docs/user-guide/workflow-setup.md

@@ -120,7 +120,7 @@ Adds a hard limit on the number of pages that will be crawled. The crawl will be
 
 ### Crawl Time Limit
 
-The crawl will be gracefully stopped after this set period of time.
+The crawl will be gracefully stopped after this set period of elapsed time.
 
 ### Crawl Size Limit
 
@@ -132,11 +132,11 @@ Increasing the amount of crawler instances will speed up crawls by using additio
 
 ### Page Load Timeout
 
-Limits amount of time to wait for a page to load. Behaviors will run after this timeout only if the page is partially or fully loaded.
+Limits amount of elapsed time to wait for a page to load. Behaviors will run after this timeout only if the page is partially or fully loaded.
 
 ### Behavior Timeout
 
-Limits how long behaviors can run on each page.
+Limits amount of elapsed time behaviors have to complete.
 
 ### Auto Scroll Behavior
 
@@ -144,7 +144,7 @@ When enabled, the browser will automatically scroll to the end of the page.
 
 ### Delay Before Next Page
 
-Waits on the page for a set period of time after any behaviors have finished running. This can be helpful to avoid rate limiting however it will slow down your crawl.
+Waits on the page for a set period of elapsed time after any behaviors have finished running. This can be helpful to avoid rate limiting however it will slow down your crawl.
 
 ## Browser Settings
 

frontend/src/pages/org/dashboard.ts

@@ -701,7 +701,9 @@ export class Dashboard extends LiteElement {
         ${msg("Total Execution Time")}
         <sl-tooltip>
           <div slot="content" style="text-transform: initial">
-            ${msg("Total running time of all crawler instances")}
+            ${msg(
+              "Total billable time of all crawler instances this used month"
+            )}
           </div>
           <sl-icon name="info-circle" style="vertical-align: -.175em"></sl-icon>
         </sl-tooltip>
@@ -712,7 +714,7 @@ export class Dashboard extends LiteElement {
       usageTableCols.push(html`${msg("Execution: Monthly")}
         <sl-tooltip>
           <div slot="content" style="text-transform: initial">
-            ${msg("Monthly execution time used on crawls this month")}
+            ${msg("Billable time used, included with monthly plan")}
           </div>
           <sl-icon name="info-circle" style="vertical-align: -.175em"></sl-icon>
         </sl-tooltip>`);
@@ -721,7 +723,9 @@ export class Dashboard extends LiteElement {
       usageTableCols.push(html`${msg("Execution: Extra")}
         <sl-tooltip>
           <div slot="content" style="text-transform: initial">
-            ${msg("Billable rollover execution time used on crawls this month")}
+            ${msg(
+              "Additional units of billable time used, any extra minutes will roll over to next month"
+            )}
           </div>
           <sl-icon name="info-circle" style="vertical-align: -.175em"></sl-icon>
         </sl-tooltip>`);
@@ -730,7 +734,9 @@ export class Dashboard extends LiteElement {
       usageTableCols.push(html`${msg("Execution: Gifted")}
         <sl-tooltip>
           <div slot="content" style="text-transform: initial">
-            ${msg("Gifted execution time used on crawls this month")}
+            ${msg(
+              "Usage of execution time added to your account free of charge"
+            )}
           </div>
           <sl-icon name="info-circle" style="vertical-align: -.175em"></sl-icon>
         </sl-tooltip>`);

mkdocs.yml

@@ -19,6 +19,8 @@ theme:
     - navigation.footer
     - content.code.copy
     - content.action.edit
+    - content.tooltips
+    - search.suggest
   palette:
     scheme: webrecorder
   logo: assets/brand/btrix-logo.svg
@@ -77,8 +79,8 @@ markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
       options:
         custom_icons:
           - docs/overrides/.icons
@@ -102,3 +104,6 @@ extra:
     - icon: bootstrap/youtube
       link: https://www.youtube.com/@webrecorder
 copyright: "Creative Commons Attribution 4.0 International (CC BY 4.0)"
+
+plugins:
+  - search