From d9b65590d8ad12e50bcf1499d369979b595f535d Mon Sep 17 00:00:00 2001
From: Dragory <2606411+Dragory@users.noreply.github.com>
Date: Fri, 25 Oct 2019 21:45:18 +0300
Subject: [PATCH] Docs work

---
 dashboard/src/components/Expandable.vue       |  11 +-
 dashboard/src/components/docs/CodeBlock.vue   |   4 +-
 .../components/docs/ConfigurationFormat.vue   |   6 +-
 dashboard/src/components/docs/DocsLayout.vue  |  12 +-
 .../src/components/docs/Introduction.vue      |   2 +-
 dashboard/src/components/docs/Permissions.vue |   8 +-
 dashboard/src/components/docs/Plugin.vue      |   8 +-
 .../components/docs/PluginConfiguration.vue   | 180 +++++++++++-------
 dashboard/src/routes.ts                       |   6 +-
 dashboard/src/style/content.pcss              |  21 +-
 10 files changed, 167 insertions(+), 91 deletions(-)

diff --git a/dashboard/src/components/Expandable.vue b/dashboard/src/components/Expandable.vue
index c9f6b38b..4728570c 100644
--- a/dashboard/src/components/Expandable.vue
+++ b/dashboard/src/components/Expandable.vue
@@ -1,6 +1,13 @@
 <template>
-  <div class="expandable mb-4 bg-gray-800 border border-gray-600 rounded overflow-hidden" ref="root" v-bind:class="{'shadow-xl': isOpen}">
-    <div role="button" class="title p-2" v-on:click="toggle">
+  <div class="expandable mb-4 bg-gray-800 border border-gray-600 rounded overflow-hidden"
+       ref="root"
+       v-bind:class="{ 'shadow-xl': isOpen}">
+    <div role="button"
+         class="title p-2 focus:bg-gray-700"
+         v-on:click="toggle"
+         v-on:keydown.space="$event.preventDefault()"
+         v-on:keyup.space="toggle"
+         tabindex="0">
       <chevron-down class="icon" v-bind:class="{'icon-open': isOpen}" />
       <span class="title-text"><slot name="title"></slot></span>
     </div>
diff --git a/dashboard/src/components/docs/CodeBlock.vue b/dashboard/src/components/docs/CodeBlock.vue
index 66499600..c4c6a7cd 100644
--- a/dashboard/src/components/docs/CodeBlock.vue
+++ b/dashboard/src/components/docs/CodeBlock.vue
@@ -1,9 +1,9 @@
 <template>
-  <pre class="codeblock" v-highlightjs><code :class="lang" v-trim-indents="trim"><slot></slot></code></pre>
+  <pre class="codeblock" v-highlightjs><code :class="codeLang" v-trim-indents="trim"><slot></slot></code></pre>
 </template>
 
 <script>
   export default {
-    props: ["lang", "trim"],
+    props: ["codeLang", "trim"],
   };
 </script>
diff --git a/dashboard/src/components/docs/ConfigurationFormat.vue b/dashboard/src/components/docs/ConfigurationFormat.vue
index 94bb5636..1d790ffa 100644
--- a/dashboard/src/components/docs/ConfigurationFormat.vue
+++ b/dashboard/src/components/docs/ConfigurationFormat.vue
@@ -7,11 +7,11 @@
 
     <ul>
       <li>Prefix (i.e. what character is preceding each command)</li>
-      <li>Permission levels (see <router-link to="/docs/permissions">Permissions</router-link> for more info)</li>
-      <li>Plugin-specific configuration (see <router-link to="/docs/plugin-configuration">Plugin configuration</router-link> for more info)</li>
+      <li>Permission levels (see <router-link to="/docs/configuration/permissions">Permissions</router-link> for more info)</li>
+      <li>Plugin-specific configuration (see <router-link to="/docs/configuration/plugin-configuration">Plugin configuration</router-link> for more info)</li>
     </ul>
 
-    <CodeBlock lang="yaml" trim="start">
+    <CodeBlock code-lang="yaml" trim="start">
       prefix: "!"
 
       # role id: level
diff --git a/dashboard/src/components/docs/DocsLayout.vue b/dashboard/src/components/docs/DocsLayout.vue
index e1781d1d..2309ceaa 100644
--- a/dashboard/src/components/docs/DocsLayout.vue
+++ b/dashboard/src/components/docs/DocsLayout.vue
@@ -70,16 +70,22 @@
           to: '/docs/introduction',
           label: 'Introduction',
         },
+      ],
+    },
+
+    {
+      label: 'Configuration',
+      items: [
         {
-          to: '/docs/configuration-format',
+          to: '/docs/configuration/configuration-format',
           label: 'Configuration format',
         },
         {
-          to: '/docs/plugin-configuration',
+          to: '/docs/configuration/plugin-configuration',
           label: 'Plugin configuration',
         },
         {
-          to: '/docs/permissions',
+          to: '/docs/configuration/permissions',
           label: 'Permissions',
         },
       ],
diff --git a/dashboard/src/components/docs/Introduction.vue b/dashboard/src/components/docs/Introduction.vue
index 899466b8..961eea84 100644
--- a/dashboard/src/components/docs/Introduction.vue
+++ b/dashboard/src/components/docs/Introduction.vue
@@ -14,7 +14,7 @@
     <h2>Configuration</h2>
     <p>
       All Zeppelin configuration is done through the dashboard by editing a YAML config file. By default, only the server
-      owner has access to this, but they can give other users access as they see fit. See <router-link to="/docs/configuration-format">Configuration format</router-link> for more details.
+      owner has access to this, but they can give other users access as they see fit. See <router-link to="/docs/configuration/configuration-format">Configuration format</router-link> for more details.
     </p>
 
     <h2>Plugins</h2>
diff --git a/dashboard/src/components/docs/Permissions.vue b/dashboard/src/components/docs/Permissions.vue
index 0932b834..e52bc624 100644
--- a/dashboard/src/components/docs/Permissions.vue
+++ b/dashboard/src/components/docs/Permissions.vue
@@ -3,7 +3,7 @@
     <h1>Permissions</h1>
     <p>
       Permissions in Zeppelin are simply values in plugin configuration that are checked when the command is used.
-      These values can be changed with overrides (see <router-link to="/docs/plugin-configuration">Plugin configuration</router-link> for more info)
+      These values can be changed with overrides (see <router-link to="/docs/configuration/plugin-configuration">Plugin configuration</router-link> for more info)
       and can depend on e.g. user id, role id, channel id, category id, or <strong>permission level</strong>.
     </p>
 
@@ -21,7 +21,7 @@
       Permission levels are defined in the config in the <strong>levels</strong> section. For example:
     </p>
 
-    <CodeBlock lang="yaml" trim="4">
+    <CodeBlock code-lang="yaml">
       # "role/user id": level
       levels:
         "172949857164722176": 100 # Example admin
@@ -39,7 +39,7 @@
       Here's what the configuration for this would look like:
     </p>
 
-    <CodeBlock lang="yaml" trim="4">
+    <CodeBlock code-lang="yaml">
       plugins:
         cats:
           config:
@@ -63,7 +63,7 @@
       Here's what the configuration for this would look like:
     </p>
 
-    <CodeBlock lang="yaml" trim="4">
+    <CodeBlock code-lang="yaml">
       plugins:
         mod_actions:
           =overrides: # The "=" here means "replace any defaults"
diff --git a/dashboard/src/components/docs/Plugin.vue b/dashboard/src/components/docs/Plugin.vue
index a6900e2d..ca71a604 100644
--- a/dashboard/src/components/docs/Plugin.vue
+++ b/dashboard/src/components/docs/Plugin.vue
@@ -10,10 +10,10 @@
 
     <Tabs>
       <Tab :active="tab === 'usage'">
-        <router-link v-bind:to="'/docs/plugins/' + pluginName + '/usage'">Usage</router-link>
+        <router-link class="unstyled" v-bind:to="'/docs/plugins/' + pluginName + '/usage'">Usage</router-link>
       </Tab>
       <Tab :active="tab === 'configuration'">
-        <router-link v-bind:to="'/docs/plugins/' + pluginName + '/configuration'">Configuration</router-link>
+        <router-link class="unstyled" v-bind:to="'/docs/plugins/' + pluginName + '/configuration'">Configuration</router-link>
       </Tab>
     </Tabs>
 
@@ -110,14 +110,14 @@
 
       <!-- Default configuration -->
       <h2 id="default-configuration">Default configuration</h2>
-      <CodeBlock lang="yaml">{{ renderConfiguration(data.defaultOptions) }}</CodeBlock>
+      <CodeBlock code-lang="yaml">{{ renderConfiguration(data.defaultOptions) }}</CodeBlock>
 
       <!-- Config schema -->
       <h2 id="config-schema">Config schema</h2>
       <Expandable class="wide">
         <template v-slot:title>Click to expand</template>
         <template v-slot:content>
-          <CodeBlock lang="plain">{{ data.configSchema }}</CodeBlock>
+          <CodeBlock code-lang="plain">{{ data.configSchema }}</CodeBlock>
         </template>
       </Expandable>
     </div>
diff --git a/dashboard/src/components/docs/PluginConfiguration.vue b/dashboard/src/components/docs/PluginConfiguration.vue
index b34b28c9..406fd316 100644
--- a/dashboard/src/components/docs/PluginConfiguration.vue
+++ b/dashboard/src/components/docs/PluginConfiguration.vue
@@ -2,93 +2,137 @@
   <div>
     <h1>Plugin configuration</h1>
     <p>
-      Each plugin in Zeppelin has its own configuration options. In the config editor, you can both set the default config
-      and overrides based on specific conditions. Permissions are also just values in the plugin's config, and thus follow
-      the same rules with overrides etc. as other options (see <router-link to="/docs/permissions">Permissions</router-link> for more info).
+      Most plugins in Zeppelin have configurable options. The values for these options come from 3 places:
+    </p>
+    <ol>
+      <li>
+        <strong>Default options</strong> (from Zeppelin)
+      </li>
+      <li>
+        <strong>Custom options</strong> (set by you in config)
+      </li>
+      <li>
+        <strong>Overrides</strong> (conditional config values, see below)
+      </li>
+    </ol>
+    <p>
+      Permissions are also just regular config options with a <code>true</code>/<code>false</code> value.
+      <router-link to="/docs/configuration/permissions">See the Permissions page for more info.</router-link>
     </p>
     <p>
-      Information about each plugin's options can be found on the plugin's page on the sidebar. See <router-link to="/docs/configuration-format">Configuration format</router-link> for an example of a full config.
+      Information about each plugin's options can be found on the plugin's page, which can be accessed from the sidebar.
+      <router-link to="/docs/configuration/configuration-format">See the Configuration format page for an example of a full config.</router-link>
     </p>
 
     <h2>Overrides</h2>
     <p>
-      Overrides are the primary mechanism of changing options and permissions based on permission levels, roles, channels, user ids, etc.
-    </p>
-    <p>
-      Here's an example demonstrating different types of overrides:
+      Overrides are the primary mechanism of changing options and permissions based on permission levels, roles,
+      channels, user ids, etc.
     </p>
 
-    <CodeBlock lang="yaml" trim="4">
-      plugins:
-        example_plugin:
-          config:
-            can_kick: false
-            kick_message: "You have been kicked"
-            nested:
-              value: "Hello"
-              other_value: "Foo"
-          overrides:
-            # Simple permission level based override to allow kicking only for levels 50 and up
-            - level: '>=50'
+    <Expandable class="wide">
+      <template v-slot:title>Click to see examples of different types of overrides</template>
+      <template v-slot:content>
+        <CodeBlock code-lang="yaml">
+          plugins:
+            example_plugin:
               config:
-                can_kick: true
+                can_kick: false
+                kick_message: "You have been kicked"
                 nested:
-                  # This only affects nested.other_value; nested.value is still "Hello"
-                  other_value: "Bar"
-            # Channel override - don't allow kicking on the specified channel
-            - channel: "109672661671505920"
-              config:
-                can_kick: false
-            # Same as above, but for a full category
-            - category: "360735466737369109"
-              config:
-                can_kick: false
-            # Multiple channels. If any of them match, this override applies.
-            - channel: ["109672661671505920", "570714864285253677"]
-              config:
-                can_kick: false
-            # Match based on a role
-            - role: "172950000412655616"
-              config:
-                can_kick: false
-            # Match based on multiple roles. The user must have ALL roles mentioned here for this override to apply.
-            - role: ["172950000412655616", "172949857164722176"]
-              config:
-                can_kick: false
-            # Match on user id
-            - user: "106391128718245888"
-              config:
-                kick_message: "You have been kicked by Dragory"
-            # Match on multiple conditions
-            - channel: "109672661671505920"
-              role: "172950000412655616"
-              config:
-                can_kick: false
-            # Match on ANY of multiple conditions
-            - any:
-              - channel: "109672661671505920"
-              - role: "172950000412655616"
-              config:
-                can_kick: false
-            # Match on either of two complex conditions
-            - any:
-              - all:
+                  value: "Hello"
+                  other_value: "Foo"
+              overrides:
+                # Simple permission level based override to allow kicking only for levels 50 and up
+                - level: '>=50'
+                  config:
+                    can_kick: true
+                    nested:
+                      # This only affects nested.other_value; nested.value is still "Hello"
+                      other_value: "Bar"
+                # Channel override - don't allow kicking on the specified channel
+                - channel: "109672661671505920"
+                  config:
+                    can_kick: false
+                # Same as above, but for a full category
+                - category: "360735466737369109"
+                  config:
+                    can_kick: false
+                # Multiple channels. If any of them match, this override applies.
+                - channel: ["109672661671505920", "570714864285253677"]
+                  config:
+                    can_kick: false
+                # Match based on a role
+                - role: "172950000412655616"
+                  config:
+                    can_kick: false
+                # Match based on multiple roles. The user must have ALL roles mentioned here for this override to apply.
+                - role: ["172950000412655616", "172949857164722176"]
+                  config:
+                    can_kick: false
+                # Match on user id
+                - user: "106391128718245888"
+                  config:
+                    kick_message: "You have been kicked by Dragory"
+                # Match on multiple conditions
                 - channel: "109672661671505920"
                   role: "172950000412655616"
-                - not:
-                    role: "473085927053590538"
-              - channel: "534727637017559040"
-                role: "473086848831455234"
-              config:
-                can_kick: false
+                  config:
+                    can_kick: false
+                # Match on ANY of multiple conditions
+                - any:
+                  - channel: "109672661671505920"
+                  - role: "172950000412655616"
+                  config:
+                    can_kick: false
+                # Match on either of two complex conditions
+                - any:
+                  - all:
+                    - channel: "109672661671505920"
+                      role: "172950000412655616"
+                    - not:
+                        role: "473085927053590538"
+                  - channel: "534727637017559040"
+                    role: "473086848831455234"
+                  config:
+                    can_kick: false
+        </CodeBlock>
+      </template>
+    </Expandable>
+
+    <h2>Default overrides</h2>
+    <p>
+      Many plugins have some overrides by default, usually for the default mod level (50) and/or the default admin level
+      (100). These are applied before any custom overrides in the config.
+    </p>
+    <p>
+      You can see the default overrides for each plugin by checking the <strong>Default configuration section</strong>
+      under the <strong>Configuration tab</strong> on the plugin's documentation page.
+    </p>
+    <p>
+      To replace a plugin's default overrides entirely, set <code>replaceDefaultOverrides</code> to <code>true</code> in
+      plugin options, on the same level as <code>config</code> and <code>overrides</code>. In the following example, any
+      default overrides the plugin had will no longer have an effect:
+    </p>
+
+    <CodeBlock code-lang="yaml">
+      example_plugin:
+        config:
+          can_kick: false
+        replaceDefaultOverrides: true # <-- Here
+        overrides:
+          - level: ">=25"
+            config:
+              can_kick: true
     </CodeBlock>
   </div>
 </template>
 
 <script lang="ts">
   import CodeBlock from "./CodeBlock.vue";
+  import Expandable from "../Expandable.vue";
 
   export default {
-    components: { CodeBlock },
+    components: { CodeBlock, Expandable },
   };
 </script>
diff --git a/dashboard/src/routes.ts b/dashboard/src/routes.ts
index 1ca49ee8..f453720e 100644
--- a/dashboard/src/routes.ts
+++ b/dashboard/src/routes.ts
@@ -24,15 +24,15 @@ export const router = new VueRouter({
           component: () => import("./components/docs/Introduction.vue"),
         },
         {
-          path: "configuration-format",
+          path: "configuration/configuration-format",
           component: () => import("./components/docs/ConfigurationFormat.vue"),
         },
         {
-          path: "permissions",
+          path: "configuration/permissions",
           component: () => import("./components/docs/Permissions.vue"),
         },
         {
-          path: "plugin-configuration",
+          path: "configuration/plugin-configuration",
           component: () => import("./components/docs/PluginConfiguration.vue"),
         },
         {
diff --git a/dashboard/src/style/content.pcss b/dashboard/src/style/content.pcss
index d359c20c..3709ad7a 100644
--- a/dashboard/src/style/content.pcss
+++ b/dashboard/src/style/content.pcss
@@ -23,7 +23,8 @@
     @apply mb-4;
   }
 
-  & a:not([class]) {
+  & a:not([class]),
+  & a[class=""] {
     @apply link;
   }
 
@@ -36,6 +37,15 @@
     }
   }
 
+  & ol:not([class]) {
+    @apply list-decimal;
+    @apply mb-4;
+
+    & li {
+      @apply ml-6;
+    }
+  }
+
   & code:not([class]) {
     @apply inline-code;
   }
@@ -44,3 +54,12 @@
     max-width: 600px;
   }
 }
+
+@screen xl {
+  .main-content {
+    & a:not([class]),
+    & a[class=""] {
+      white-space: nowrap;
+    }
+  }
+}