Skip to content

Commit

Permalink
rework documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Zwiterrion committed Jun 6, 2024
1 parent 5199ba6 commit e3f1ede
Show file tree
Hide file tree
Showing 21 changed files with 346 additions and 73 deletions.
5 changes: 4 additions & 1 deletion cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
8 changes: 4 additions & 4 deletions docs/documentation/app/builder/collaborate/_page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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' }} />
Expand Down
11 changes: 9 additions & 2 deletions docs/documentation/app/cli/getting-started/_page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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
Expand Down
109 changes: 109 additions & 0 deletions docs/documentation/app/faq/_page.mdx
Original file line number Diff line number Diff line change
@@ -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)
7 changes: 7 additions & 0 deletions docs/documentation/app/faq/layout.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import Page from './page';

export const metadata = {
title: 'FAQ',
}

export default Page;
20 changes: 20 additions & 0 deletions docs/documentation/app/faq/page.js
Original file line number Diff line number Diff line change
@@ -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>

}
34 changes: 34 additions & 0 deletions docs/documentation/app/globals.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
7 changes: 7 additions & 0 deletions docs/documentation/components/Badge.js
Original file line number Diff line number Diff line change
@@ -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>
}
4 changes: 2 additions & 2 deletions docs/documentation/components/Badges.js
Original file line number Diff line number Diff line change
@@ -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>)}
Expand Down
21 changes: 21 additions & 0 deletions docs/documentation/components/FAQButton.js
Original file line number Diff line number Diff line change
@@ -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>
}
2 changes: 1 addition & 1 deletion docs/documentation/components/Layout.js
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
4 changes: 3 additions & 1 deletion docs/documentation/components/Searchbar.js
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down
67 changes: 60 additions & 7 deletions docs/documentation/components/Sidebar.js
Original file line number Diff line number Diff line change
Expand Up @@ -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, '')
Expand All @@ -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} >
Expand Down Expand Up @@ -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>
})}
Expand Down
Loading

0 comments on commit e3f1ede

Please sign in to comment.