Skip to content

Improve doveadm documentation #1108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slusarz merged 5 commits into from
Dec 20, 2024
Merged

Improve doveadm documentation #1108

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2e0bbf8
doveadm: Add support for adding example arguments to doveadm commands
slusarz Dec 13, 2024
9f5c1b5
doveadm: Output HTTP API examples for each command
slusarz Dec 14, 2024
edfe7d7
doveadm: CLI usage information should be displayed the same as HTTP API
slusarz Dec 18, 2024
1d67227
doveadm: Add missing man pages to various entries
slusarz Dec 18, 2024
25e850c
doveadm: Rework response documentation
slusarz Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions components/DoveadmCliComponent.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<script setup>
/* Properties for this component:
* 'data' (object): The command argument data.
*/
const props = defineProps(['data'])
const d = props.data
</script>

<template>
<div>
<ul>
<li>Usage: <code>doveadm {{ d.usage }}</code></li>
</ul>

<table v-if="d.args">
<thead>
<tr>
<th>Argument(s)</th>
<th>Type</th>
<th>Description</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<template v-for="elem in d.args">
<tr>
<td><code>{{ elem.flag }}</code></td>
<td>{{ elem.type }}</td>
<td v-html="elem.text" />
<td><code v-if="elem.example !== undefined">{{ JSON.stringify(elem.example) }}</code></td>
</tr>
</template>
</tbody>
</table>
</div>
</template>
80 changes: 25 additions & 55 deletions components/DoveadmComponent.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
<script setup>
import { data } from '../lib/data/doveadm.data.js'
import { ref } from 'vue'

/* Properties for this component:
* 'plugin' (string): Filter by the plugin property.
Expand All @@ -16,6 +17,16 @@ const d = Object.fromEntries(Object.entries(data.doveadm).filter(([k, v]) =>
((v.plugin && v.plugin == props.tag) ||
(v.tags.includes(props.tag))))
).sort())

const cliComponent = ref({})
function cliClick(k) {
cliComponent.value[k] = 'DoveadmCliComponent'
}

const httpComponent = ref({})
function httpClick(k) {
httpComponent.value[k] = 'DoveadmHttpApiComponent'
}
</script>

<style scoped>
Expand All @@ -38,7 +49,7 @@ const d = Object.fromEntries(Object.entries(data.doveadm).filter(([k, v]) =>
<a class="header-anchor" :href="'#' + k"></a>
</h3>

<table v-if="v.man_link || v.fields || v.added || v.changed || v.deprecated || v.removed">
<table v-if="v.man_link || v.response || v.added || v.changed || v.deprecated || v.removed">
<tbody>
<tr v-if="v.man_link">
<th style="text-align: right;">Man Page</th>
Expand Down Expand Up @@ -69,20 +80,22 @@ const d = Object.fromEntries(Object.entries(data.doveadm).filter(([k, v]) =>
</td>
</tr>

<tr v-if="v.fields">
<th style="text-align: right;">Return Values</th>
<tr v-if="v.response">
<th style="text-align: right;">Response Values</th>
<td>
<table>
<thead>
<tr>
<th>Key</th>
<th>Value</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr v-for="elem in v.fields">
<tr v-for="elem in v.response">
<td><code>{{ elem.key }}</code></td>
<td v-html="elem.value" />
<td v-html="elem.type" />
<td v-html="elem.text" />
</tr>
</tbody>
</table>
Expand All @@ -93,58 +106,15 @@ const d = Object.fromEntries(Object.entries(data.doveadm).filter(([k, v]) =>

<div v-if="v.text" v-html="v.text" />

<div class="info custom-block">
<p class="custom-block-title">CLI</p>
<div>
<ul>
<li>Usage: <code>doveadm {{ v.usage }}</code></li>
</ul>

<table v-if="v.args">
<thead>
<tr>
<th>Argument(s)</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<template v-for="elem in v.args">
<tr>
<td><code>{{ elem.flag }}</code></td>
<td>{{ elem.type }}</td>
<td v-html="elem.text" />
</tr>
</template>
</tbody>
</table>
</div>
</div>
<details @click.capture.once="cliClick(k)" class="details custom-block">
<summary>CLI</summary>
<component v-if="cliComponent[k]" :is="cliComponent[k]" :data="v" />
</details>

<details v-if="v.args" class="details custom-block">
<details v-if="v.args" @click.capture.once="httpClick(k)" class="details custom-block">
<summary v-html="data.http_api_link" />
<div>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<template v-for="elem in v.args">
<tr>
<td><code>{{ elem.param }}</code></td>
<td>{{ elem.type }}</td>
<td v-html="elem.text" />
</tr>
</template>
</tbody>
</table>
</div>
<component v-if="httpComponent[k]" :is="httpComponent[k]" :data="v" />
</details>

</article>
</section>
</template>
118 changes: 118 additions & 0 deletions components/DoveadmHttpApiComponent.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
<script setup>
/* Properties for this component:
* 'data' (object): The command argument data.
*
* Note: Clipboard behavior is handled by re-using the Vitepress code.
*/
const props = defineProps(['data'])
const d = props.data

const args = {}
for (let elem of d.args.filter(e => e.example !== undefined && !e.cli_only)) {
args[elem.param] = elem.example
}

const jsonReq =
[
[
d.http_cmd,
args,
"tag1"
]
]

const resp = {}
if (d.response) {
for (let elem of d.response) {
resp[elem.key] = elem.example
}
}

const jsonResp =
[
[
"doveadmResponse",
[ resp ],
"tag1"
]
]
</script>

<template>
<div>
<p class="custom-block-title">
Command Name: <code>{{ d.http_cmd }}</code>
</p>

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<template v-for="elem in d.args">
<tr v-if="!elem.cli_only">
<td><code>{{ elem.param }}</code></td>
<td>{{ elem.type }}</td>
<td v-html="elem.text" />
<td><code v-if="elem.example">{{ JSON.stringify(elem.example) }}</code></td>
</tr>
</template>
</tbody>
</table>

<p class="custom-block-title">Example Request Payload</p>

<div class="language- vp-adaptive-theme">
<button class="copy" title="Copy" />
<span class="lang"></span>
<pre><code>{{ JSON.stringify(jsonReq, null, 4) }}</code></pre>
</div>

<p class="custom-block-title">Example Curl Request (using Dovecot API Key)</p>

<div class="language- vp-adaptive-theme">
<button class="copy" title="Copy" />
<span class="lang"></span>
<pre><code>curl -X POST -H "Authorization: X-Dovecot-API &lt;base64 encoded dovecot_api_key&gt;" -H "Content-Type: application/json" -d '{{ JSON.stringify(jsonReq) }}' http://example.com:8080/doveadm/v1</code></pre>
</div>

<p class="custom-block-title">Example Curl Request (using Doveadm Password)</p>

<div class="language- vp-adaptive-theme">
<button class="copy" title="Copy" />
<span class="lang"></span>
<pre><code>curl -X POST -u doveadm:secretpassword -H "Content-Type: application/json" -d '{{ JSON.stringify(jsonReq) }}' http://example.com:8080/doveadm/v1</code></pre>
</div>

<p class="custom-block-title">Example Wget Request (using Dovecot API Key)</p>

<div class="language- vp-adaptive-theme">
<button class="copy" title="Copy" />
<span class="lang"></span>
<pre><code>wget --header="Authorization: X-Dovecot-API &lt;base64 encoded dovecot_api_key&gt;" --header="Content-Type: application/json" --post-data='{{ JSON.stringify(jsonReq) }}' --output-document - http://example.com:8080/doveadm/v1</code></pre>
</div>

<p class="custom-block-title">Example Wget Request (using Doveadm Password)</p>

<div class="language- vp-adaptive-theme">
<button class="copy" title="Copy" />
<span class="lang"></span>
<pre><code>wget --header="Content-Type: application/json" --user=doveadm --password=password --auth-no-challenge --post-data='{{ JSON.stringify(jsonReq) }}' --output-document - http://example.com:8080/doveadm/v1</code></pre>
</div>

<template v-if="d.response?.length">
<p class="custom-block-title">Example Server Response</p>

<div class="language- vp-adaptive-theme">
<button class="copy" title="Copy" />
<span class="lang"></span>
<pre><code>{{ JSON.stringify(jsonResp, null, 4) }}</code></pre>
</div>
</template>
</div>
</template>
Loading
Loading