update docusaurus and add mobile enrollment state machine doc (#461)

* update docusaurus and add mobile enrollment state machine doc

* update node version in github workflows

* fix jetstream url issues

* swap file type from mdx to md

* remove additional rollout graph and not-selected reason

.github/workflows/documentation.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: "12.x"
+          node-version: "16.x"
       - name: Test Build
         run: |
           yarn install --frozen-lockfile
@@ -26,7 +26,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: "12.x"
+          node-version: "16.x"
       - name: Add key to allow access to repository
         env:
           SSH_AUTH_SOCK: /tmp/ssh_agent.sock

docs/deep-dives/mobile/enrollment-state-machine.md

@@ -0,0 +1,119 @@
+---
+id: mobile-enrollment-state-machine
+title: Enrollment State Machine
+slug: /mobile-enrollment-state-machine
+---
+
+## Possible States
+
+Within the Nimbus SDK there are multiple states, most of which have a "reason" associated with them.
+The reason field functions as a child state, and is required for parent states that have reasons.
+
+### Enrolled
+
+#### Qualified
+
+The client is not already enrolled in a recipe of the same type that would result in a feature conflict, and matched targeting and bucketing criteria for this recipe<sup><a href="#notes">[1]</a></sup>.
+
+#### Opt In
+
+The client explicitly opted into this recipe<sup><a href="#notes">[2]</a></sup>.
+
+### Not Enrolled
+
+:::info
+This state and its reasons are for enrollments that have never been enrolled, and did not enroll.
+:::
+
+#### Not Selected
+
+The client did not fall into the bucketing selected for this recipe.
+
+#### Not Targeted
+
+The client did not match the criteria set forth by the targeting string.
+
+#### Opt Out
+
+The client has opted out of experimentation at the application level.
+
+#### EnrollmentsPaused
+
+The recipe has paused enrollments.
+
+#### Feature Conflict
+
+The feature(s) the recipe targets a) are being experimented on by another recipe of the same type in which the client is already enrolled<sup><a href="#notes">[3]</a></sup>, and b) are not enabled for coenrollment.
+
+### Disqualified
+
+:::info
+This state and its reasons are for enrollments that were previously in one of the `Enrolled` states, but are no longer enrolled.
+:::
+
+#### Not Targeted
+
+_See [NotEnrolled::NotTargeted](#not-targeted)_
+
+#### Opt Out
+
+The client manually opted out of the recipe<sup><a href="#notes">[2]</a></sup>.
+
+#### Error
+
+The client threw an error during enrollment re-evaluation.
+
+### Was Enrolled
+
+The recipe has ended, and the client was enrolled at some point.
+The `Enrolled` and `Disqualified` statuses end up here when a recipe ends.
+
+### Error
+
+The client threw an error during enrollment evaluation<sup><a href="#notes">[4]</a></sup>.
+
+### Notes
+
+1. The explicit order in which recipe criteria are evaluated is as follows:
+    1. Feature conflicts
+    2. Targeting
+    3. Bucketing
+2. This state can be reached via Firefox mobile's secret menu.
+3. Experiments and rollouts do not share feature conflicts.
+   A client can be enrolled in up to one rollout and one experiment for a given feature, unless that feature has been enabled for coenrollment.
+4. This status will only contain enrollments for recipes in which the client has never been enrolled.
+   If the client is enrolled but throws an error during enrollment re-evaluation it will be moved to [Disqualified::Error](#error)
+
+## State Diagrams
+
+The following state diagrams describe the interactions between states for the enrollment state machine in the mobile Nimbus SDK.
+
+### Experiments
+```mermaid
+stateDiagram-v2
+    direction LR
+
+    [*] --> enrolled
+    [*] --> not_enrolled
+
+    enrolled: Enrolled
+    not_enrolled: Not Enrolled
+    disqualified: Disqualified
+    was_enrolled: Was Enrolled
+    error: Error
+
+    enrolled --> disqualified
+
+    state on_experiment_ended <<join>>
+    enrolled --> on_experiment_ended
+    disqualified --> on_experiment_ended
+    on_experiment_ended --> was_enrolled: on experiment ended
+
+    was_enrolled --> [*]: on garbage\ncollect (1yr)
+
+    not_enrolled --> enrolled: if enrollment is not paused
+    error --> enrolled: if enrollment is not paused
+
+    not_enrolled --> error: on error
+    enrolled --> error: on error
+```

docs/jetstream/jetstream.md

@@ -1,6 +1,7 @@
 ---
 id: jetstream
 title: Jetstream overview
+slug: /jetstream/jetstream
 ---
 
 **[Jetstream]** is an analysis framework for experiments.

docusaurus.config.js

@@ -1,70 +1,79 @@
 module.exports = {
-      title: "Experimenter Docs",
-  tagline: "Documentation souce for Data scientists, Product Managers and Engineers",
-  url: "https://experimenter.info",
-  baseUrl: "/",
-  onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
-  favicon: "img/favicon.ico",
-  organizationName: "mozilla",
-  projectName: "experimenter-docs",
-  themeConfig: {
-    prism: {
-      additionalLanguages: ["kotlin", "swift", "rust", "toml"]
-    },
-    hideableSidebar: true,
-    colorMode: {
-      defaultMode: "light",
-      disableSwitch: true,
-      respectPrefersColorScheme: true,
-    },
-    navbar: {
-      title: "Mozilla Experimentation and Feature Delivery",
-      logo: {
-        alt: "Experimenter Logo",
-        src: "img/logo.svg",
-        srcDark: "img/logo-dark.svg",
-      },
-      items: [
-        {
-          href: "https://experimenter.services.mozilla.com/nimbus/",
-          label: "Nimbus",
-          position: "right",
+    title: "Experimenter Docs",
+    tagline: "Documentation souce for Data scientists, Product Managers and Engineers",
+    url: "https://experimenter.info",
+    baseUrl: "/",
+    onBrokenLinks: "throw",
+    onBrokenMarkdownLinks: "warn",
+    favicon: "img/favicon.ico",
+    organizationName: "mozilla",
+    projectName: "experimenter-docs",
+    themeConfig: {
+        prism: {
+            additionalLanguages: ["kotlin", "swift", "rust", "toml"]
         },
-        {
-          href: "https://mozilla-hub.atlassian.net/wiki/spaces/FJT/pages/11470446/Nimbus",
-          label: "Confluence",
-          position: "right",
-        },
-        {
-          href: "https://github.com/mozilla/experimenter-docs",
-          position: "right",
-          className: "header-github-link",
-          "aria-label": "GitHub repository",
-        },
-      ],
-    },
-    footer: {
-      copyright: `Copyright © ${new Date().getFullYear()} Mozilla Corporation`,
-    },
-    algolia: {
-      apiKey: "cce683dfea9772207408c2b161a22641",
-      indexName: "experimenter",
-    },
-  },
-  presets: [
-    [
-      "@docusaurus/preset-classic",
-      {
         docs: {
-          routeBasePath: "/",
-          sidebarPath: require.resolve("./sidebars.js"),
-          editUrl: "https://github.com/mozilla/experimenter-docs/edit/main/",
+            sidebar: {
+                hideable: true
+            }
         },
-        theme: {
-          customCss: require.resolve("./src/css/custom.css"),
+        colorMode: {
+            defaultMode: "light",
+            disableSwitch: true,
+            respectPrefersColorScheme: true,
         },
-      },
+        navbar: {
+            title: "Mozilla Experimentation and Feature Delivery",
+            logo: {
+                alt: "Experimenter Logo",
+                src: "img/logo.svg",
+                srcDark: "img/logo-dark.svg",
+            },
+            items: [
+                {
+                    href: "https://experimenter.services.mozilla.com/nimbus/",
+                    label: "Nimbus",
+                    position: "right",
+                },
+                {
+                    href: "https://mozilla-hub.atlassian.net/wiki/spaces/FJT/pages/11470446/Nimbus",
+                    label: "Confluence",
+                    position: "right",
+                },
+                {
+                    href: "https://github.com/mozilla/experimenter-docs",
+                    position: "right",
+                    className: "header-github-link",
+                    "aria-label": "GitHub repository",
+                },
+            ],
+        },
+        footer: {
+            copyright: `Copyright © ${new Date().getFullYear()} Mozilla Corporation`,
+        },
+        algolia: {
+            appId: 'experimenter',
+            apiKey: "cce683dfea9772207408c2b161a22641",
+            indexName: "experimenter",
+        },
+    },
+    presets: [
+        [
+            "@docusaurus/preset-classic",
+            {
+                docs: {
+                    routeBasePath: "/",
+                    sidebarPath: require.resolve("./sidebars.js"),
+                    editUrl: "https://github.com/mozilla/experimenter-docs/edit/main/",
+                },
+                theme: {
+                    customCss: require.resolve("./src/css/custom.css"),
+                },
+            },
+        ],
     ],
-  ],
+    markdown: {
+        mermaid: true,
+    },
+    themes: ['@docusaurus/theme-mermaid'],
 };

package.json

@@ -12,10 +12,10 @@
     "clear": "docusaurus clear"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-beta.5",
-    "@docusaurus/preset-classic": "^2.0.0-beta.6",
-    "@mdx-js/react": "^1.6.21",
-    "clsx": "^1.1.1",
+    "@docusaurus/core": "^2.4.1",
+    "@docusaurus/preset-classic": "^2.4.1",
+    "@docusaurus/theme-mermaid": "^2.4.1",
+    "clsx": "^1.2.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   },