Merge pull request #907 from gravwell/dev

dev -> master

README.md

@@ -11,6 +11,123 @@ Inside of the nix-shell:
 - build the documentation by running `make html`
 - view changes as you edit by running `make livehtml` and visit http://127.0.0.1:8000
 
+## Deploying
+
+### Paths
+
+In order for the version switcher to work properly, the paths where we serve the docs have to have the following structure:
+
+- Docs for latest release are at `/`
+  - Ends up being the target for old links, so old links continue to work as they always have
+- Docs for previous releases are at `/vN.N.N/`
+
+For example, if we're publishing v5.4.5, v5.4.4, and v5.4.3...
+
+- `https://docs.gravwell.io` is v5.4.5
+- `https://docs.gravwell.io/v5.4.4/` is v5.4.4
+- `https://docs.gravwell.io/v5.4.3/` is v5.4.3
+
+### Directory structure
+
+Assume we're using a web server to serve a directory as `docs.gravwell.io`.
+
+If we wanted to serve v5.4.5, v5.4.4, and v5.4.3 as shown above, we could structure the directory like this:
+
+```
+docs/     <- the full build of v5.4.5. Serve this directory as `/`
+├─ 404.html
+├─ index.html
+├─ ...
+├─ v5.4.4/   <- the full build of v5.4.4
+│  ├─ 404.html
+│  ├─ index.html
+│  ├─ ...
+├─ v5.4.3/   <- the full build of v5.4.3
+│  ├─ 404.html
+│  ├─ index.html
+│  ├─ ...
+```
+
+Builds of previous versions in are nested within the latest version, so we end up with the paths we want.
+
+Links would also work:
+
+```
+docs/
+├─ latest/      <- a link to v5.4.5. Serve this directory as `/`
+│  ├─ v5.4.4/   <- a link to v5.4.4
+│  ├─ v5.4.3/   <- a link to v5.4.3
+│  ├─ ...
+├─ v5.4.5/   <- the full build of v5.4.5
+│  ├─ 404.html
+│  ├─ index.html
+│  ├─ ...
+├─ v5.4.4/   <- the full build of v5.4.4
+│  ├─ 404.html
+│  ├─ index.html
+│  ├─ ...
+├─ v5.4.3/   <- the full build of v5.4.3
+│  ├─ 404.html
+│  ├─ index.html
+│  ├─ ...
+```
+
+### versions.json
+
+`https://docs.gravwell.io/_static/verions.json` dictates how the version selector will behave in all docs versions, past and current.
+
+As implied by the path, only the `versions.json` that's included in the latest docs version needs to be up-to-date. It doesn't matter if any `.../vN.N.N/_static/versions.json` is out of date. Only the file at `/_static/verions.json` is used.
+
+The [PyData Sphinx Theme docs](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html#add-a-json-file-to-define-your-switcher-s-versions) explain the options in more detail, but here's a quick summary / example:
+
+```js
+[
+  {
+    // An optional special name to show in the selector
+    name: "v5.4.5 (latest)",
+
+    // The version. Should match `release` in `conf.py`
+    version: "v5.4.5",
+
+    // The path where one will be able to find this release (root path for latest)
+    url: "https://docs.gravwell.io/",
+
+    // Set to true if this is the latest version.
+    // If set to false or omited, an "Old Version" warning banner will show on that version.
+    // Only one entry in the versions array may have preferred set to true.
+    preferred: true,
+  },
+
+  {
+    // Since "name" is missing, the selector will just show "v5.4.4"
+    version: "v5.4.4",
+    url: "https://docs.gravwell.io/v5.4.4/",
+    //  Since preferred is omitted, the "Old Version" warning banner will show for v5.4.4
+  },
+
+  {
+    // Since "name" is missing, the selector will just show "v5.4.3"
+    version: "v5.4.3",
+    url: "https://docs.gravwell.io/v5.4.3/",
+    //  Since preferred is omitted, the "Old Version" warning banner will show for v5.4.3
+  },
+];
+```
+
+When updating version.json...
+
+- push a new entry in the front of the array
+  - Ensure `name` and `preferred` are set as necessary
+- unset `preferred` and `name` for the entry that's now at index 1
+- remove old releases from the end as necessary (see below)
+
+### Removing old releases
+
+As verions accumulate, we may decide to stop hosting old versions. This requires:
+
+1. Updating `_static/versions.json` hosted at `https://docs.gravwell.io/_static/versions.json`, so that it contains only those versions we want to continue hosting
+2. Removing old versions from the web server
+
 ## Adding Sphinx Extensions
 
 Adding a Sphinx extension requires two steps:

_static/css/custom.css

@@ -138,12 +138,21 @@ nav.bd-links p.bd-links__title {
   background: unset;
 }
 
+.navbar-brand.logo img {
+  height: 80%;
+  margin-top: 14px;
+}
+
 @media (min-width: 960px) {
   .bd-page-width {
     max-width: 1800px;
   }
 }
 
+button.btn.version-switcher__button {
+  margin-bottom: unset;
+}
+
 .bd-main .bd-content .bd-article-container {
   max-width: 100%;
 }
@@ -169,3 +178,59 @@ div.docutils button.copybtn:hover {
 div.docutils button.copybtn:active {
   background-color: rgb(187, 187, 187);
 }
+
+/*
+
+BEGIN DYNAMIC NAVBAR LINKS
+
+In `dynamic-navbar.html`, we create 8 different navbars.
+
+Each navbar `N` shows `N` links, and puts the remaining `8 - N` links in the "More" dropdown.
+
+The styles below use media queries to dictate which of the 8 navbars will show given the width of the page.
+*/
+
+/* By default, none of the 8 navbars are displayed. */
+.bd-header .navbar-nav.default-hidden-nav {
+  display: none;
+}
+
+/* Depending on the width of the page, we decide which nav to show */
+
+@media (960px <= width < 1035px) {
+  #nav-2 {
+    display: inherit;
+  }
+}
+@media (1035px <= width < 1240px) {
+  #nav-3 {
+    display: inherit;
+  }
+}
+@media (1240px <= width < 1305px) {
+  #nav-4 {
+    display: inherit;
+  }
+}
+@media (1305px <= width < 1430px) {
+  #nav-5 {
+    display: inherit;
+  }
+}
+@media (1430px <= width < 1480px) {
+  #nav-6 {
+    display: inherit;
+  }
+}
+@media (1480px <= width < 1530px) {
+  #nav-7 {
+    display: inherit;
+  }
+}
+@media (min-width: 1530px) {
+  #nav-8 {
+    display: inherit;
+  }
+}
+
+/* END DYNAMIC NAVBAR LINKS */

_static/versions.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "v5.4.3 (latest)",
+    "version": "v5.4.3",
+    "url": "https://docs.gravwell.io/",
+    "preferred": true
+  }
+]

_templates/dynamic-navbar.html

@@ -0,0 +1,10 @@
+{# Create a bunch of headers that are hidden by default. #}
+{# Use style in custom.css to show at appropriate page widths. #}
+
+{% for i in range(1, 9) %}
+<nav id="nav-{{loop.index}}" class="navbar-nav default-hidden-nav">
+  <ul class="bd-navbar-elements navbar-nav">
+    {{ generate_header_nav_html(n_links_before_dropdown=loop.index, dropdown_text=theme_header_dropdown_text) }}
+  </ul>
+</nav>
+{% endfor %}

_templates/git-commit-footer.html

@@ -1,3 +1,6 @@
 <p class="docs-version">
-  Documentation version <code class="git-commit-id">{{git_commit}}</code>
+  Documentation for Gravwell {{release}} (docs build
+  <a href="https://github.com/gravwell/wiki/commit/{{git_commit}}">
+    <code class="git-commit-id">{{git_commit}}</code></a
+  >{{"*" if git_dirty_tree}})
 </p>

_templates/layout.html

@@ -15,9 +15,18 @@
   {{ super() }}
 
   <script>
-    $(document).ready(function(){
-      $('[data-toggle="popover"]').popover();
-    });
+    const popoverTriggerList = Array.from(
+      document.querySelectorAll('[data-bs-toggle="popover"]')
+    ).map((el) => new bootstrap.Popover(el));
   </script>
 
 {% endblock scripts_end %}
+
+{# Search wasn't showing matches because sphinx's searchtools.js wasn't finding role="main" #}
+{# This overrides the docs_boxy block to add the role attribute. Fixes search troubles. #}
+{% block docs_body %}
+  {% include "components/searchbox.html" %}
+  <article class="bd-article" role="main">
+    {% block body %}{% endblock %}
+  </article>
+{% endblock docs_body %}

_templates/sections/header.html

@@ -0,0 +1,56 @@
+{#
+    This is basically the original header.html, but with some overridden bootstrap cols to help keep the navbar from wrapping all silly.
+
+    If navbar_start has col-lg-3, the version switcher will wrap in an unpleasant way at certain widths.
+
+    See https://github.com/pydata/pydata-sphinx-theme/blob/6010af1af74db163398092b1f6e721e7da631b02/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html
+#}
+
+{% if theme_navbar_start or theme_navbar_center or theme_navbar_end or theme_navbar_persistent %}
+<div class="bd-header__inner bd-page-width">
+  <label class="sidebar-toggle primary-toggle" for="__primary">
+    <span class="fa-solid fa-bars"></span>
+  </label>
+  {% set navbar_start, navbar_class, navbar_align = navbar_align_class() %}
+  {% if theme_navbar_start %}
+  <div class="col-xl-3 col-lg-4 navbar-header-items__start">
+    {% for navbar_item in theme_navbar_start %}
+      <div class="navbar-item">{% include navbar_item %}</div>
+    {% endfor %}
+  </div>
+  {% endif %}
+  <div class="col-xl-9 col-lg-8  navbar-header-items">
+    {% if theme_navbar_center %}
+    <div class="{{ navbar_align }} navbar-header-items__center">
+      {% for navbar_item in theme_navbar_center %}
+        <div class="navbar-item">{% include navbar_item %}</div>
+      {% endfor %}
+    </div>
+    {% endif %}
+    {% if theme_navbar_end or theme_navbar_persistent %}
+    <div class="navbar-header-items__end">
+      {% for navbar_item in theme_navbar_persistent %}
+        <div class="navbar-item navbar-persistent--container">
+          {% include navbar_item %}
+        </div>
+      {% endfor %}
+      {% for navbar_item in theme_navbar_end %}
+        <div class="navbar-item">{% include navbar_item %}</div>
+      {% endfor %}
+    </div>
+    {% endif %}
+  </div>
+  {# A search button to show up only on mobile #}
+  {% for navbar_item in theme_navbar_persistent %}
+    <div class="navbar-persistent--mobile">
+      {%- include navbar_item %}
+    </div>
+  {% endfor %}
+
+  {% if not remove_sidebar_secondary and secondary_sidebar_items %}
+    <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
+      <span class="fa-solid fa-outdent"></span>
+    </label>
+  {% endif %}
+</div>
+{% endif %}

alerts/alerts.md

@@ -21,6 +21,18 @@ Alerts are defined in the Alerts page, found under the Automation sub-menu. Clic
 
 Note that we have populated the Name, Description, Target Tag, and Max Events fields, but nothing else yet -- we need to go define our dispatchers and consumers before we can add them to the alert.
 
+Also notice that there are some optional toggles. The first one will allow us to enable the Alert once it is properly configured. The second one allows us to enable Search Retention. 
+
+
+### Selecting a Tag
+
+Every event generated by your dispatchers will be ingested into the Target Tag in JSON format. In general, we recommend the following:
+
+* Pick a unique tag for each alert you define, and make sure your user has [permission to ingest to that tag](/cbac/cbac).
+* Use a prefix, such as `_alerts_`, for all your target tags. This makes it easier to define a separate well to store alerts in, if desired.
+
+In this example, we have chosen the tag `_alerts_admin_logins`.
+
 ### Max Events
 
 The "Max Events" configuration option is an important safeguard against accidentally sending yourself thousands of emails. Basically, when a dispatcher fires, Gravwell will only process *up to* Max Events results from the search. Suppose you have a scheduled search dispatcher which normally generates one or two results, which are emailed out via a flow consumer. If a new data source is added and the scheduled search suddenly returns thousands of results each time, you could be getting thousands of emails -- unless you've been cautious and set Max Events to a low value!
@@ -31,14 +43,9 @@ Gravwell sets a very low default for Max Events, because it is extremely easy to
 Setting Max Events to 0 is equivalent to setting it to 8192, the max value
 ```
 
-### Selecting a Tag
-
-Every event generated by your dispatchers will be ingested into the Target Tag in JSON format. In general, we recommend the following:
+### Search Retention
 
-* Pick a unique tag for each alert you define, and make sure your user has [permission to ingest to that tag](/cbac/cbac).
-* Use a prefix, such as `_alerts_`, for all your target tags. This makes it easier to define a separate well to store alerts in, if desired.
-
-In this example, we have chosen the tag `_alerts_admin_logins`.
+The search retention option will allow any search that dispatches the Alert to be saved as a Persistent Search for a specified period of time. The retention time is configurable with a default of 7 days. After that time, the Persistent Search will be automatically deleted.
 
 ## Adding Dispatchers