Merge branch 'master' into littledata-docs-update

Author: edwardupton

CODEOWNERS

@@ -1,17 +1,18 @@
 # The default owners for everything in
 # the repo. Unless a later match takes precedence.
-CODEOWNERS  @segmentio/segment-doc-team
+CODEOWNERS  @segmentio/segment-doc-team @sanscontext @markzegarelli
 
 # Diagram library
-/diagram-library @sanscontext
+/diagram-library @sanscontext @markzegarelli
 
 # Utility scripts
-/scripts @segmentio/segment-doc-team @XavierAgostini
+/scripts @segmentio/segment-doc-team
 
 # Vale Linting
 /vale-styles @segmentio/segment-doc-team
 .vale.ini @segmentio/segment-doc-team
 
+
 # Content owners should be in the order of PM, TL (team-lead), and EM (in a crisis) for a given team.
 # This team will receive review requests automatically when a PR is submitted modifying the files in
 # a given directory+subtree, or file type, etc. that matches below.  While Github won't enforce the
@@ -23,16 +24,16 @@ CODEOWNERS  @segmentio/segment-doc-team
 # Libraries owners
 /src/connections/catalog/libraries  @osamakhn @bsneed @pooyaj @juliofarah
 
-# Destination owners
+# Destinations owners
 /src/connections/destinations  @segmentio/segment-doc-team
 
 
-# Privacy owners
-/src/privacy    @notfelineit
+# Privacy owners TODO
+# /src/privacy
 
 
-# Protocols owners
-/src/protocols  @francisco @rarchana2001asu
+# Protocols owners TODO
+# /src/protocols
 
 # Partner Program owners
 /src/partners  @misteryeo @n2parko @benhorowitz

Gemfile

@@ -17,6 +17,7 @@ group :jekyll_plugins do
   gem 'jekyll-redirect-from'
   gem "premonition", "~> 2.0.0"
   gem "jekyll-include-cache"
+  gem 'jekyll-algolia'
 end
 
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem

Gemfile.lock

@@ -23,6 +23,12 @@ GEM
   specs:
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
+    algolia_html_extractor (2.6.4)
+      json (~> 2.0)
+      nokogiri (~> 1.10)
+    algoliasearch (1.27.5)
+      httpclient (~> 2.8, >= 2.8.3)
+      json (>= 1.5.1)
     colorator (1.1.0)
     commonmarker (0.21.0)
       ruby-enum (~> 0.5)
@@ -36,10 +42,21 @@ GEM
       multipart-post (>= 1.2, < 3)
       ruby2_keywords
     ffi (1.13.1)
+    filesize (0.2.0)
     forwardable-extended (2.6.0)
     http_parser.rb (0.6.0)
+    httpclient (2.8.3)
     i18n (1.8.5)
       concurrent-ruby (~> 1.0)
+    jekyll-algolia (1.6.0)
+      algolia_html_extractor (~> 2.6)
+      algoliasearch (~> 1.26)
+      filesize (~> 0.1)
+      jekyll (>= 3.6, < 5.0)
+      json (~> 2.0)
+      nokogiri (~> 1.6)
+      progressbar (~> 1.9)
+      verbal_expressions (~> 0.1.5)
     jekyll-commonmark (1.3.1)
       commonmarker (~> 0.14)
       jekyll (>= 3.7, < 5.0)
@@ -56,6 +73,7 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
+    json (2.5.1)
     kramdown (2.3.0)
       rexml
     kramdown-parser-gfm (1.1.0)
@@ -67,12 +85,20 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
+    mini_portile2 (2.5.0)
     multipart-post (2.1.1)
+    nokogiri (1.11.1)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    nokogiri (1.11.1-x86_64-linux)
+      racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     posix-spawn (0.3.15)
     premonition (2.0.1)
+    progressbar (1.11.0)
     public_suffix (4.0.6)
+    racc (1.5.2)
     rake (13.0.1)
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
@@ -93,6 +119,7 @@ GEM
     tzinfo-data (1.2020.4)
       tzinfo (>= 1.0.0)
     unicode-display_width (1.7.0)
+    verbal_expressions (0.1.5)
     wdm (0.1.1)
 
 PLATFORMS
@@ -103,6 +130,7 @@ DEPENDENCIES
   dotenv
   faraday
   jekyll!
+  jekyll-algolia
   jekyll-commonmark
   jekyll-include-cache
   jekyll-last-modified-at

_config.yml

@@ -49,3 +49,8 @@ plugins:
   - premonition
   - jekyll-commonmark
   - jekyll-last-modified-at
+algolia:
+  application_id: UINQ2M4D9S
+  index_name:     segment-docs
+  files_to_exclude:
+    - _release_notes/*

devguide.md

@@ -33,6 +33,20 @@ Occasionally, a destination will change names. This shouldn't be too difficult t
   2. The programmatic content appears (cmodes, settings, previous names)
   3. The redirect from the old page URL works.
 
+## All about the Catalog script
+
+You run the Catalog update script by running `make catalog` from the docs repo. You, a person who is going to run the script, must first save a Segment token to an `.env` file locally, which is `gitignored` so we don’t check it in to gihub accidentally.
+
+Note: Old ConfigAPI tokens are not compatible with Public API. You'll need a new one if you want to use Public API.
+
+The script takes your token, inserts it into a request header, then contacts the API, downloads all the available metadata for destinations and sources. It then writes them into a series of yml files that the docs build can consume. (You can find these in `/src/_data/catalog/`)
+
+Note: We don’t currently (Feb '21) do this for warehouses (storage dests) because they were originally lumped in with destinations, and didn’t change often enough to be worth writing a script for. We just have a static `warehouses.yml` file instead. With the switch to Public API from ConfigAPI, we should change this.
+
+The script also “calculates” the values for the `connection-modes` table for destinations, but that’s a huge other headache.
+
+It also does some slugification and destination-name normalization, since our handling of dots and dashes hasn't been consistent over time. Finally, it checks to see if there’s a folder for each destination. If it finds a new one, the script makes a folder with a “stub” markdown file for that destination, and then adds a line for it to an "incompleteDocs.txt" file. (It doesn't check to see if it's already listed, just appends to the file.)
+
 
 ## Developer information
 

js/algolia/index.js

@@ -0,0 +1,80 @@
+import { html } from 'htm/preact';
+import algoliasearch from 'algoliasearch/lite';
+import { autocomplete, getAlgoliaHits, highlightHit } from '@algolia/autocomplete-js';
+import {createAlgoliaInsightsPlugin} from '@algolia/autocomplete-plugin-algolia-insights';
+import insightsClient from 'search-insights';
+
+
+const appId = 'UINQ2M4D9S';
+const apiKey = '636b6d9e2dfb207e89ea7344859848f9';
+const searchClient = algoliasearch(appId, apiKey);
+
+//insights
+insightsClient('init', { appId, apiKey });
+const algoliaInsightsPlugin = createAlgoliaInsightsPlugin({ insightsClient });
+
+
+const search = autocomplete({
+  container: '#autocomplete',
+  placeholder: 'Search the Segment documentation',
+  debug: false,
+  openOnFocus: false,
+  keyboardShortcuts: ['s', 191],
+  plugins: [algoliaInsightsPlugin,],
+  detachedMediaQuery:'none',
+  getSources( {query} ) {
+    return [
+      {
+        sourceId: 'articles',
+        getItemUrl({ item }){
+          if (item.anchor != null) {
+            var itemUrl = item.url+"#" + item.anchor;
+          } else {
+            var itemUrl = item.url;
+          }
+          return itemUrl;
+        },
+        getItems() {
+          return getAlgoliaHits({
+            searchClient,
+            queries: [
+              {
+                indexName: 'segment-docs',
+                query,
+                params: {
+                  hitsPerPage: 7,
+                  facetFilters: ['hidden:-true'],
+                  clickAnalytics: true,
+                },
+              },
+            ],
+          });
+        },
+        templates: {
+          item({ item }){
+            if (item.anchor != null) {
+              var anchorLink = "#" + item.anchor;
+            } else {
+              var anchorLink = "";
+            }
+            return html `<a class="aa-link" href="/docs${item.url}${anchorLink}">
+            <p class="aa-title" >${highlightHit({hit: item, attribute: 'title'})}</h3>
+            <p class="aa-heading">${item.headings.join(' >')}</p>
+            <p class="aa-content">${highlightHit({hit: item, attribute: 'content'})}</p></a>
+          `;
+          },
+          noResults() {
+            return html `<p class="aa-content">No results for <strong>${query}</strong></p>`;
+          }
+        },
+        
+      },
+    ];
+  },
+  navigator: {
+    navigate({ itemUrl }) {
+      window.location.assign('/docs'+itemUrl);
+    },
+  }
+});
+

js/hoverhelp/index.js

@@ -0,0 +1,34 @@
+const COMPONENT_NAME = 'data-hoverhelp'
+const COMPONENT_SELECTOR = `[${COMPONENT_NAME}]`
+const BODY_SELECTOR = 'data-hoverhelp-body'
+const TRIGGER_SELECTOR = '[data-hoverhelp-target]'
+
+export default function () {
+  const components = document.querySelectorAll(COMPONENT_SELECTOR)
+
+  for (let i = 0; i < components.length; i++) {
+    const triggers = components[i].querySelectorAll(TRIGGER_SELECTOR)
+
+    for (let i = 0; i < triggers.length; i++) {
+      triggers[i].addEventListener('mouseover', e => {
+        e.preventDefault()
+
+        const targetBody = document.querySelector(`[${BODY_SELECTOR}=${e.target.dataset.hoverhelpTarget}]`)
+
+        components[i].classList.toggle(components[i].dataset.activeClass)
+      })
+    }
+
+    document.addEventListener('mouseover', e => {
+      if (components[i].classList.contains(components[i].dataset.activeClass)) {
+        const hoverhelpBody = components[i].querySelector(`[${BODY_SELECTOR}]`)
+
+        for (let i = 0; i < triggers.length; i++) {
+          if (!hoverhelpBody.contains(e.target) && e.target !== triggers[i]) {
+            components[i].classList.remove(components[i].dataset.activeClass)
+          }
+        }
+      }
+    })
+  }
+}

js/index.js

@@ -9,6 +9,7 @@ import dropdownMenu from './dropdown-menu'
 import anchorsIndicator from './anchors-indicator'
 import codeExample from './code-example'
 import popover from './popover'
+import hoverhelp from './hoverhelp'
 import menuPanels from './menu-panels'
 import searchBar404 from './search-bar-404'
 import backScrolling from './back-scrolling'
@@ -18,6 +19,7 @@ import sideMenu from './side-menu'
 import tracking from './tracking'
 import searchBar from './search-bar'
 import glightbox from './glightbox'
+import autocomplete from './algolia'
 feedback()
 accordion()
 accordionGroup()
@@ -30,11 +32,12 @@ dropdownMenu()
 anchorsIndicator()
 codeExample()
 popover()
+hoverhelp()
 searchBar404()
 backScrolling()
 navigation()
 relativeLinks()
 sideMenu()
 tracking()
 searchBar()
-glightbox()
+glightbox()

js/search-navbar/index.js

@@ -22,7 +22,7 @@ export default function () {
     }
   }
 
-  document.getElementsByClassName('st-search-input')[0].addEventListener('click', function () {
+  document.getElementsByClassName('aa-Input')[0].addEventListener('click', function () {
     typewriter.searchClicked()
   })
 }

js/tracking/index.js

@@ -35,7 +35,7 @@ export default function() {
     };
   };
 
-  Array.from(document.querySelectorAll('.st-search-input')).forEach(searchInput => {
+  Array.from(document.querySelectorAll('.aa-Input')).forEach(searchInput => {
     searchInput.addEventListener('input', debounce(function(e) {
       const query = e.target.value
       if (query.length) {