Merge branch 'master' into littledata-docs-update

Author: edwardupton

.buildkite/pipeline.yml

@@ -12,3 +12,6 @@ src/assets/docs.bundle.js
 yarn-error.log
 # Make sure to update `analytics` to the full path to your Typewriter client.
 .vscode/spellright.dict
+
+# Local Netlify folder
+.netlify

.gitignore

@@ -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

CODEOWNERS

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

Gemfile

@@ -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,13 +42,27 @@ 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)
+    jekyll-dotenv (0.2.0)
+      dotenv (~> 2.7)
+      jekyll (~> 4)
     jekyll-include-cache (0.2.1)
       jekyll (>= 3.7, < 5.0)
     jekyll-last-modified-at (1.3.0)
@@ -56,7 +76,8 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (2.3.0)
+    json (2.5.1)
+    kramdown (2.3.1)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
@@ -67,12 +88,22 @@ 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-darwin)
+      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,17 +124,21 @@ 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
   ruby
-  x86_64-linux-musl
+  x86_64-darwin-20
+  x86_64-linux
 
 DEPENDENCIES
   dotenv
   faraday
   jekyll!
+  jekyll-algolia
   jekyll-commonmark
+  jekyll-dotenv
   jekyll-include-cache
   jekyll-last-modified-at
   jekyll-redirect-from

Gemfile.lock

@@ -189,9 +189,9 @@ Each piece of frontmatter does something special!
 #### Content-related frontmatter
 - `beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta-note.md`)
 - `rewrite`: defaults to false. This is a legacy frontmatter flag that comes from the old `site-docs` repo, and which labels any destination that was rewritten in ~2018 to a standardized template. It disables the duplicate "connection modes" table that would otherwise show up in the boilerplate content at the end of the page.
-- `hide-boilerplate`: defaults to false. When true, none of the content from `integration-foot.md` is appended to the destination page.
+- `hide-boilerplate`: defaults to false. When true, none of the content from `destination-footer.md` is appended to the destination page.
 - `hide-cmodes`: defaults to false. A renaming of "rewrite" for more clarity, hides the connection modes table in the boilerplate.
-- `hide-personas-partial`: defaults to false. When true, hides the section of content from `integration-foot.md` that talks about being able to receive personas data.
+- `hide-personas-partial`: defaults to false. When true, hides the section of content from `destination-footer.md` that talks about being able to receive personas data.
 - `integration_type`: This is set in the `_config.yml` on three paths to add a noun (Source, Destination, or Warehouse) to the end of the title, and the end of the title tag in the html layout. It also controls the layout and icon for some of these.
 - `source-type`: These are only used to supplement when a Cloud App in the sources path doesn't appear in the Config API list, and needs its type explicitly set. It runs some logic in the `cloud-app-note.md` to explain which cloud-apps are object vs event sources.
 

README.md

@@ -25,12 +25,12 @@ defaults:
       path: "connections/destinations/catalog"
     values:
       integration_type: destination
-      layout: integration
+      layout: destination
   - scope:
       path: "connections/sources/catalog"
     values:
       integration_type: source
-      layout: integration
+      layout: source
   - scope:
       path: "connections/storage/catalog"
     values:
@@ -49,3 +49,9 @@ plugins:
   - premonition
   - jekyll-commonmark
   - jekyll-last-modified-at
+  - jekyll-dotenv
+algolia:
+  application_id: UINQ2M4D9S
+  index_name:     segment-docs
+  files_to_exclude:
+    - _release_notes/*

_config.yml

@@ -47,21 +47,45 @@ The script also “calculates” the values for the `connection-modes` table for
 
 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.)
 
+### Connection Modes in the Catalog script
+
+As part of the Dossiers project we worked on making the Connection Modes table more readable. Originally we were going to have per-page liquid run, but these modes don't change often so it would've added a lot of build time for very little benefit. Instead we pushed it into `catalog.js`.
+Once the connection modes device and cloud arrays are set, we do a bunch of calculations, and add a text summary, a number which corresponds to that summary for easier programmatic writing, and a rough category.
+
+| Case | Summary                                | Type        | Message                                                                                                                                                     |
+| ---- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | No data available                      | none        | No connection mode information available.                                                                                                                   |
+| 1    | Both device, no cloud                  | device-only | accepts device-mode data from both Analytics.js and mobile sources. It does not accept data in cloud-mode.                                                  |
+| 2    | AJS (web device) only                  | device-only | accepts device-mode data only from Analytics.js.                                                                                                            |
+| 3    | Mobile device mode only                | device-only | accepts device-mode data only from a mobile source.                                                                                                         |
+| 4    | Accepts from all                       | all         | accepts cloud-mode data from all Segment source types. It can accept device-mode data from both web and mobile sources.                                     |
+| 5    | All cloud types                        | cloud-only  | accepts cloud-mode data from all Segment source types. It does not offer device-mode connections.                                                           |
+| 6    | Mobile and Server cloud only           | cloud-only  | accepts data from any Segment mobile or server source in cloud mode. It does not accept data from a web source, and does not offer device-mode connections. |
+| 7    | Web and mobile cloud only              | cloud-only  | accepts only cloud-mode data from web and mobile sources.                                                                                                   |
+| 8    | Mobile cloud only                      | cloud-only  | accepts only cloud-mode data from mobile sources.                                                                                                           |
+| 9    | All cloud types, 1 device mode         | mixed       | accepts data in cloud-mode from all source types, and can accept data in device-mode from [Analytics.js or mobile] sources.                                 |
+| 10   | Web and mobile cloud, 1 device         | mixed       | accepts data in cloud-mode from web and mobile sources, and can accept data in device-mode from [Analytics.js or mobile] sources.                           |
+| 11   | Mobile and server cloud, mobile device | mixed       | accepts data in cloud-mode from mobile and server sources, and can accept data in device-mode from mobile sources.                                          |
 
 ## Developer information
 
 
 ### Layouts
 
-`default.html` is the base container through which all the individual other layouts (currently one, `page.html`) are built to have the right title, seo, etc. `Integration.html` contains the logic that runs the catalog pages.
+`default.html` is the base container through which all the individual other layouts are built to have the right title, seo, etc. The template inheritance is described in the diagram below.
+
+The `destination.html`, `source.html`, and `integration.html` templates contain the logic that runs the layouts for individual catalog pages. Storage/warehouses use the generic Integration right now because they don't need anything special. Set the layout in the Jekyll `_config.yml` file.
 
 ```text
 default.html
- |- integration.html
- |- catalog.html
- |- main.html
-    |-page.html
-    |-home.html
+  |- integration.html
+    |- destination.html
+    |- source.html
+  |- main.html
+    |- catalog.html - used for connections catalog pages only
+    |- home.html - for main landing page only
+    |- page.html - used for all pages outside Connections catalogs, without an explicit override
+    |- search.html - search results page only
 ```
 
 ### Platform Config API + Catalog

devguide.md

@@ -0,0 +1,86 @@
+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 });
+
+// define locations to separate invocation for mobile and desktop
+const locations = ['#autocomplete','#autocomplete-mobile'];
+
+function initAutocomplete(item){
+  const search = autocomplete({
+    container: item,
+    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);
+      },
+    }
+  });
+  
+}
+
+locations.forEach(initAutocomplete);