rework documentation

MAIF · Jun 6, 2024 · e3f1ede · e3f1ede
1 parent 5199ba6
commit e3f1ede
Show file tree

Hide file tree

Showing 21 changed files with 346 additions and 73 deletions.
diff --git a/cli/README.md b/cli/README.md
@@ -67,7 +67,10 @@ Then open the content of your `my-first-plugin` folder. You should find the gene
 
 You can now optionally start a new plugin from a template by appending `--template=[template-name]` to the creation command.
 
-If you don't pass a template, Wasmo will list the available templates: `js`, `ts`, `opa`, `go` and `rust`.
+If you don't pass a template, Wasmo will list the available templates. There are listed by product : 
+  - empty template : `js`, `ts`, `opa`, `go` and `rust`
+  - Otoroshi template : `otoroshi_go`, `otoroshi_rust`, `otoroshi_opa`, `otoroshi_ts`, `otoroshi_js`
+  - Izanami template : `izanami_js`, `izanami_go`, `izanami_rust`, `izanami_opa`, `izanami_ts`
 
 ```
 wasmo init --name=my-first-plugin --template=[template-name] --path=[output-directory]

diff --git a/docs/documentation/app/builder/collaborate/_page.mdx b/docs/documentation/app/builder/collaborate/_page.mdx
@@ -3,10 +3,10 @@
 
 Wasmo 1.2.2 brings a new feature to collaborate inside the product. You can work together on a plugin by sharing it with collaborators. It's easy to share plugins with your entire team. 
 
-1. In Wasmo, on the left, click Share plugin.
-2. Email can be added to two lists : the first to allow users to edit, view and share plugin, and the second, more restrictive, where users can only
-edit and view plugins.
-3. Click Update authorized people
+To share plugins from the UI:
+  1. Click on the desired plugin
+  2. Click the 🔗 button
+  3. Write administrators and users emails in their respective lists
 
 <div style={{ display: 'flex', justifyContent: 'center', width: '100%', marginTop: '2rem' }}>
   <img src="/wasmo/collaborate.png" width={500} style={{ borderRadius: '.5rem' }} />

diff --git a/docs/documentation/app/cli/getting-started/_page.mdx b/docs/documentation/app/cli/getting-started/_page.mdx
@@ -43,7 +43,10 @@ Then open the content of your `my-first-plugin` folder. You should find the gene
 
 You can now optionally start a new plugin from a template by appending `--template=[template-name]` to the creation command.
 
-If you don't pass a template, Wasmo will list the available templates: `js`, `ts`, `opa`, `go` and `rust`.
+If you don't pass a template, Wasmo will list the available templates. There are listed by product : 
+  - empty template : `js`, `ts`, `opa`, `go` and `rust`
+  - Otoroshi template : `otoroshi_go`, `otoroshi_rust`, `otoroshi_opa`, `otoroshi_ts`, `otoroshi_js`
+  - Izanami template : `izanami_js`, `izanami_go`, `izanami_rust`, `izanami_opa`, `izanami_ts`
 
 ```
 wasmo init --name=my-first-plugin --template=[template-name] --path=[output-directory]
@@ -61,7 +64,11 @@ You have two ways to build your plugin:
 
 [wasmoserver]: https://github.com/MAIF/wasmo
 
-Assuming we want to build our `my-first-plugin` locally. Enter `wasmo build --host=OneShotDocker --path=my-first-plugin` to start the build. 
+Assuming we want to build our `my-first-plugin` locally. Enter the following command to start the build. 
+
+```
+wasmo build --host=OneShotDocker --path=my-first-plugin
+```
 
 Let's explain these 3 parameters:
   - the `path` parameter is explicitly used to indicate the plugin to build

diff --git a/docs/documentation/app/faq/_page.mdx b/docs/documentation/app/faq/_page.mdx
@@ -0,0 +1,109 @@
+import Badge from '../../components/Badge'
+import Badges from '../../components/Badges'
+import FAQButton from '../../components/FAQButton'
+
+# FAQ
+
+<FAQButton title="What is the fastest way to use Wasmo?" />
+<FAQButton title="How to create an Otoroshi-compatible plugin using Docker?" />
+<FAQButton title="How can I create a new development version of my plugin?" />
+<FAQButton title="Can I download the generated Wasm from the UI?" />
+<FAQButton title="Can I determine who built each version and at what time?" />
+<FAQButton title="How to collaborate with my team ?" />
+<FAQButton title="Our team have a CI/CD process and wants to automate the building of our plugins." />
+<FAQButton title="How can I collaborate with my team?" />
+
+### What is the fastest way to use Wasmo?
+
+```
+$ cargo install wasmo
+or
+$ brew tap maif/wasmo
+$ brew install wasmo
+```
+
+### How to create an Otoroshi-compatible plugin using Docker? 
+<Badge raw value="Name : foo" default/>
+
+Initialize the plugin with corresponding Otoroshi template and Javascript language 
+``` 
+wasmo init --template=otoroshi_js --name=foo
+```
+
+Build plugin from folder and Docker
+```
+wasmo build --host=OneShotDocker --path=.
+```
+
+### How can I create a new development version of my plugin?
+<Badges raw values={["Name : foo", "Version : 1.0.2"]} default/>
+
+Rust plugin
+
+``` Cargo.toml
+[package]
+name = "foo"
+version = "1.0.2"
+
+...
+```
+
+JS/TS/Open Policy Agent plugin
+
+``` package.json
+{
+  "name": "foo",
+  "version": "1.0.2",
+  ...
+}
+```
+
+Go plugin
+
+``` go.mod
+module foo/1.0.2
+
+...
+```
+
+<div style={{ display: 'flex', justifyContent: 'center', width: '100%', marginTop: '2rem' }}>
+  <img src="/wasmo/release.png" style={{  borderRadius: '.5rem',
+    width: '230px',
+    maxWidth: '230px',
+    height: '503px',
+    minHeight: '503px'
+  }} />
+
+  <div className="flex flex-col ms-5">
+    ### Can I download the generated Wasm from the UI?
+
+    Once you have built a dev or release version of your plugin using the Hammer or Rocker buttons (available at the top right of the screen),
+    you can click on each version under the 'Releases' section on the left side of the screen.
+
+    ### Can I determine who built each version and at what time?
+
+    Each plugin has a **config** file under the **configuration** section with the following information : 
+      - type: language used to develop the plugin.
+      - users: list of users allowed to edit and view the plugin.
+      - admins: list of admins allowed to edit, view and share the plugin.
+      - filename: name of the plugin.
+      - pluginId: unique ID of the plugin.
+      - template: original template, selected at plugin creation.
+      - **versions: list of built versions, with name, creator and date of generation**.
+      - last_hash: hash used by the backend to check if changes has been made between last version.
+  </div>
+</div>
+
+### How can I collaborate with my team?
+
+Since version 1.22, Wasmo allows users to share plugins with two levels of rights: 
+- `users`: Can edit and view plugin.
+- `admins`: Can edit, view and share plugin.
+
+You can find more information about sharing by reading this [article](/wasmo/builder/collaborate)
+
+### Our team have a CI/CD process and wants to automate the building of our plugins.
+
+Since version 1.x, Wasmo includes a command line interface to create, edit and build plugins. 
+
+You can find more [information](/wasmo/cli/getting-started) about the CLI and the Github [repository](https://github.com/MAIF/wasmo/tree/main/cli)
diff --git a/docs/documentation/app/faq/layout.js b/docs/documentation/app/faq/layout.js
@@ -0,0 +1,7 @@
+import Page from './page';
+
+export const metadata = {
+  title: 'FAQ',
+}
+
+export default Page;
diff --git a/docs/documentation/app/faq/page.js b/docs/documentation/app/faq/page.js
@@ -0,0 +1,20 @@
+"use client"
+
+import Layout from '@/components/Layout';
+import Page from './_page.mdx';
+
+export default function Home() {
+
+  return <Layout
+    metadata={{
+      title: 'FAQ',
+      href: '/cli/examples'
+    }}
+    next={{
+      href: "/builder/getting-started",
+      title: "Builder - Getting started"
+    }}>
+    <Page />
+  </Layout>
+
+}
diff --git a/docs/documentation/app/globals.css b/docs/documentation/app/globals.css
@@ -16,4 +16,38 @@
     overflow: auto;
     max-height: calc(500px - 71px);
     margin-bottom: 24px;
+}
+
+.sidebar-group::before {
+    position: absolute;
+    bottom: -0.1rem;
+    top: -0.1rem;
+    left: -0.5rem;
+    width: 10px;
+    --tw-border-opacity: 1;
+    border-right-width: 2px;
+    border-color: rgb(226 232 240 / var(--tw-border-opacity));
+    opacity: 1;
+    content: "";
+}
+
+.sidebar-group-selected::before {
+    border-color: rgb(126 34 206);
+}
+
+h2, h3 {
+    position: relative;
+}
+
+.anchor-link {
+    color: #666;
+    opacity: 0;
+    position: absolute;
+    transform: translate(-1em, -2px);
+    width: 1em;
+}
+
+h3:hover .anchor-link,
+h2:hover .anchor-link {
+    opacity: 1;
 }
diff --git a/docs/documentation/components/Badge.js b/docs/documentation/components/Badge.js
@@ -0,0 +1,7 @@
+export default function Badge({ value, raw, ...props }) {
+    return <div className={`inline-flex flex items-center ${props.default ? 'mb-3' : 'ms-3 mt-2 '}`} style={{ gap: '.5rem' }}>
+        <span className="whitespace-nowrap rounded-full bg-purple-100 px-2.5 py-0.5 text-sm text-purple-700">
+            {!raw ? `<${value}>` : value}
+        </span>
+    </div>
+}
diff --git a/docs/documentation/components/Badges.js b/docs/documentation/components/Badges.js
@@ -1,5 +1,5 @@
-export default function Badges({ values, raw  }) {
-    return <div className="inline-flex ms-6 flex items-center mt-2" style={{ gap: '.5rem' }}>
+export default function Badges({ values, raw, ...props }) {
+    return <div className={`inline-flex flex items-center ${props.default ? 'mb-3' : 'ms-6  mt-2 '}`} style={{ gap: '.5rem' }}>
         {values.map(value => <span key={value} className="whitespace-nowrap rounded-full bg-purple-100 px-2.5 py-0.5 text-sm text-purple-700">
             {!raw ? `<${value}>` : value}
         </span>)}

diff --git a/docs/documentation/components/FAQButton.js b/docs/documentation/components/FAQButton.js
@@ -0,0 +1,21 @@
+export default function FAQButton({ title }) {
+    return <button className="block btn border border-black p-2 w-4/5 text-start rounded-lg mb-3 flex items-center justify-between" type="button"
+        onClick={() => {
+            window.location.href = `/wasmo/faq#${title
+                .toLowerCase()
+                .replace(/[^a-z0-9 ]/g, '')
+                .replace(/[ ]/g, '-')}`
+        }}>
+        <div className="items-center flex gap-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" width={24}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+            </svg>
+            {title}
+        </div>
+
+
+        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.25} stroke="currentColor" width={24}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M15.042 21.672 13.684 16.6m0 0-2.51 2.225.569-9.47 5.227 7.917-3.286-.672ZM12 2.25V4.5m5.834.166-1.591 1.591M20.25 10.5H18M7.757 14.743l-1.59 1.59M6 10.5H3.75m4.007-4.243-1.59-1.59" />
+        </svg>
+    </button>
+}
diff --git a/docs/documentation/components/Layout.js b/docs/documentation/components/Layout.js
@@ -49,7 +49,7 @@ function Layout({ children, next, metadata, previous }) {
           table: Table,
           th: props => <th className='whitespace-nowrap px-4 py-2 font-medium text-gray-900'>{props.children}</th>,
           thead: props => <thead className="ltr:text-left rtl:text-right">{props.children}</thead>,
-          h3: props => <h3 className='text-xl font-bold my-3'>{props.children}</h3>,
+          h3: Heading.H3,
           h4: props => <h4 className='text-lg my-3'>{props.children}</h4>
         }}>
           {children}

diff --git a/docs/documentation/components/Searchbar.js b/docs/documentation/components/Searchbar.js
@@ -70,7 +70,9 @@ export default function Searchbar({ handleOpen, open }) {
           paddingTop: open ? 20 : 6
         }}>
           <div id="search" style={{ display: open ? 'initial' : 'none' }}></div>
-          {!open && <div className='cursor-pointer p-2 bg-purple-700 rounded-xl items-center flex'>
+          {!open && <div className='cursor-pointer p-2 rounded-xl items-center flex' style={{
+            background: 'rgb(126 34 206)'
+          }}>
             <svg viewBox="0 0 20 20"
               aria-hidden="true"
               className="h-auto w-5 fill-white">

diff --git a/docs/documentation/components/Sidebar.js b/docs/documentation/components/Sidebar.js
@@ -2,12 +2,12 @@
 const LINKS = {
   Builder: ["Getting started", "Your first plugin", "Environment Variables", "Plugin Structure", "Collaborate", 'UI'],
   CLI: ["Getting started", "Core commands", "Configuration file"],
-  Integrations: ["Otoroshi"],
+  Integrations: ["Otoroshi"]
 }
 
-const SELECTED = "bg-gray-400";
+const NEWS = ["FAQ"]
 
-const color = test => test ? SELECTED : 'transparent';
+const color = test => test ? "#002451" : 'transparent';
 const slugify = str => str.toString()
   .normalize('NFD')
   .replace(/[\u0300-\u036f]/g, '')
@@ -31,11 +31,41 @@ export function Sidebar({ metadata }) {
         <li>
           <a
             href="/wasmo"
-            className={`block rounded-lg ${color(metadata.href === "/wasmo")} px-4 py-2 text-sm font-medium text-gray-700`}
+            className={`block rounded-lg ${color(metadata.href === "/wasmo")} px-4 ps-3 py-2 text-sm font-medium text-gray-700`}
           >
             Overview
           </a>
         </li>
+        <li className="relative">
+          <a
+            href="/wasmo/faq"
+            className={`flex block rounded-lg ps-3 py-2 ps-2 hover:bg-gray-100 hover:text-gray-700 ${color(metadata.href === "/faq")} text-sm font-medium text-gray-700`}
+          >
+            FAQ
+            <div style={{
+              marginLeft: 'auto',
+              display: "inline-flex",
+              alignItems: 'center',
+              justifyContent: 'center',
+              height: '1.25rem',
+              fontSize: '.875rem',
+              lineHeight: '1.25rem',
+              width: '-moz-fit-content',
+              width: 'fit-content',
+              paddingLeft: '0.563rem',
+              paddingRight: '0.563rem',
+              borderRadius: '1.2rem',
+              borderWidth: '1px',
+              '--p': 'rgb(126, 34, 206)',
+              '--tw-border-opacity': 1,
+              borderColor: 'var(--fallback-b2,oklch(var(--p)/var(--tw-border-opacity)))',
+              '--tw-bg-opacity': 1,
+              backgroundColor: 'var(--fallback-b1,oklch(var(--b2)/var(--tw-bg-opacity)))',
+              '--tw-text-opacity': 1,
+              color: 'var(--fallback-bc,oklch(var(--p)/var(--tw-text-opacity)))'
+            }}>New</div>
+          </a>
+        </li>
 
         {Object.entries(LINKS).map(([group, children]) => {
           return <li key={group} >
@@ -65,15 +95,38 @@ export function Sidebar({ metadata }) {
                 </span>
               </summary>
 
-              <ul className="mt-2 space-y-1 px-4">
+              <ul className="mt-2 space-y-1 ps-4">
                 {children.map(child => {
                   const href = `/wasmo/${slugify(group)}/${slugify(child)}`;
-                  return <li key={child}>
+                  return <li key={child} className="relative">
                     <a
                       href={href}
-                      className={`block rounded-lg px-2 py-2 text-sm font-medium text-gray-500 hover:bg-gray-100 hover:text-gray-700 ${color(`/wasmo/${metadata.href}` === href)}`}
+                      className={`flex block rounded-lg px-3 py-1 text-sm font-medium text-gray-500 hover:bg-gray-100 hover:text-gray-700 sidebar-group ${`/wasmo${metadata.href}` === href ? 'sidebar-group-selected' : ''}`}
                     >
                       {child}
+
+                      {NEWS.includes(child) && <div style={{
+                        marginLeft: 'auto',
+                        display: "inline-flex",
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        height: '1.25rem',
+                        fontSize: '.875rem',
+                        lineHeight: '1.25rem',
+                        width: '-moz-fit-content',
+                        width: 'fit-content',
+                        paddingLeft: '0.563rem',
+                        paddingRight: '0.563rem',
+                        borderRadius: 'var(--rounded-badge,1.9rem)',
+                        borderWidth: '1px',
+                        '--p': 'rgb(126, 34, 206)',
+                        '--tw-border-opacity': 1,
+                        borderColor: 'var(--fallback-b2,oklch(var(--p)/var(--tw-border-opacity)))',
+                        '--tw-bg-opacity': 1,
+                        backgroundColor: 'var(--fallback-b1,oklch(var(--b2)/var(--tw-bg-opacity)))',
+                        '--tw-text-opacity': 1,
+                        color: 'var(--fallback-bc,oklch(var(--p)/var(--tw-text-opacity)))'
+                      }}>New</div>}
                     </a>
                   </li>
                 })}