Add ability to download raw "data files" used to build documentation

.github/actions/spelling/expect.txt

@@ -119,6 +119,7 @@ cydir
 cyrusimap
 datacenter
 DATAERR
+datafiles
 datalake
 datastack
 datastax
@@ -541,6 +542,7 @@ noout
 nopassword
 nopipelining
 nordirplus
+noreferrer
 noscheme
 noselect
 nosep

.gitignore

@@ -13,3 +13,4 @@ lib/data/*.mjs
 .vitepress/local.js
 .vitepress/.temp
 /man/
+public/datafiles/

.vitepress/config.js

@@ -4,6 +4,7 @@ import { pagefindPlugin } from 'vitepress-plugin-pagefind'
 import { generateSidebar } from 'vitepress-sidebar'
 import { dovecotMdExtend } from '../lib/markdown.js'
 import { getExcludes } from '../lib/utility.js'
+import dovecotVitepressInit from '../lib/dovecot_vitepress_init.js'
 
 const base = '/2.4'
 const base_url = 'https://doc.dovecot.org'
@@ -62,7 +63,8 @@ export default defineConfig({
 			chunkSizeWarningLimit: 1000,
 		},
 		plugins: [
-			pagefindPlugin()
+			pagefindPlugin(),
+			dovecotVitepressInit()
 		],
 	},
 

components/DoveadmComponent.vue

@@ -15,7 +15,7 @@ const d = Object.fromEntries(Object.entries(data.doveadm).filter(([k, v]) =>
 	 (v.plugin && v.plugin == props.plugin)) ||
 	(props.tag &&
 	 ((v.plugin && v.plugin == props.tag) ||
-	  (v.tags.includes(props.tag))))
+	  (v.tags?.includes(props.tag))))
 ).sort())
 
 const cliComponent = ref({})

components/EventsComponent.vue

@@ -14,7 +14,7 @@ const d = Object.fromEntries(Object.entries(data).filter(([k, v]) =>
 	  (v.root && v.root == props.root)) ||
 	 (props.tag &&
 	  ((v.root && v.root == props.tag) ||
-	   (v.tags.includes(props.tag)))))
+	   (v.tags?.includes(props.tag)))))
 ).sort())
 </script>
 

components/SettingsComponent.vue

@@ -22,10 +22,10 @@ const d = Object.fromEntries(Object.entries(data).filter(([k, v]) =>
 	/* Filter entries (by plugin or tag). */
 	((!props.plugin && !tag) ||
 	 (props.plugin &&
-	  (v.plugin && v.plugin.includes(props.plugin))) ||
+	  v.plugin?.includes(props.plugin)) ||
 	 (tag && tag.find((t) =>
-	  (v.plugin && v.plugin.includes(t)) ||
-	  (v.tags.includes(t)))
+	  v.plugin?.includes(t) ||
+	  v.tags?.includes(t))
 	 )) &&
 	/* Apply filter. */
 	((filter == 'all') ||
@@ -88,21 +88,21 @@ const d = Object.fromEntries(Object.entries(data).filter(([k, v]) =>
        <span class="comma" v-for="v in v.values" v-html="v.url" />
       </td>
      </tr>
-     <tr v-if="v.values_enum.length">
+     <tr v-if="v.values_enum?.length">
       <th>Allowed Values</th>
       <td>
        <span class="comma" v-for="v in v.values_enum.values()"><code>{{ v }}</code></span>
       </td>
      </tr>
-     <tr v-if="v.dependencies.length">
+     <tr v-if="v.dependencies?.length">
       <th>Dependencies</th>
       <td>
        <ul>
         <li v-for="v in v.dependencies" v-html="v" />
        </ul>
       </td>
      </tr>
-     <tr v-if="v.seealso.length">
+     <tr v-if="v.seealso?.length">
       <th>See Also</th>
       <td>
        <ul>

data/doveadm.js

@@ -24,7 +24,7 @@ export const doveadm = {
 				// If set, will use as command example argument.
 				// i.e., for HTTP API requests, this argument will be added
 				// to the example argument string.
-				example: false,
+				// example: "foo",
 
 				// If true, this is an optional positional argument.
 				// optional: true,

data/events.js

@@ -29,7 +29,7 @@ export const events = {
 
 		// Event(s) this field inherits fields from.
 		// Can be a single event or an array of events.
-		inherit: '',
+		// inherit: '',
 
 		// List of fields emitted. Keys are field names, values are
 		// descriptions (string) or an object with multiple keys (see below for

data/settings.js

@@ -2131,8 +2131,7 @@ fts_header_includes {
 	fts_header_includes: {
 		plugin: 'fts',
 		values: setting_types.BOOLLIST,
-		seealso: [ 'fts_header_excludes' ],
-		text: ``
+		seealso: [ 'fts_header_excludes' ]
 	},
 
 	fts_search_timeout: {

docs/core/datafiles.md

@@ -0,0 +1,40 @@
+---
+layout: doc
+title: Raw Data Files
+---
+
+<script setup>
+import { data } from '../../lib/data/datafiles.data.js'
+import { withBase } from 'vitepress'
+</script>
+
+# Raw Data Files
+
+This page provides download links to the raw data files used to generate the
+Dovecot documentation.
+
+The format and content of each data file is available by looking at the data
+file source in GitHub (links for each file below).
+
+## Data File List
+
+<table>
+ <thead>
+  <tr>
+   <th>File</th>
+   <th>Source</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr v-for="file in data.files">
+   <td>
+    <code>
+     <a :href="withBase(file.download)" target="_blank" rel="noreferrer">{{ file.name }}</a>
+    </code>
+   </td>
+   <td>
+    <a :href="file.github" target="_blank" rel="noreferrer">Source</a>
+   </td>
+  </tr>
+ </tbody>
+</table>

lib/data/datafiles.data.js

@@ -0,0 +1,16 @@
+import { dataFileList } from '../datafiles.js'
+
+const filedata = []
+for (const d of dataFileList) {
+	filedata.push({
+		download: d.download,
+		github: d.github,
+		name: d.name
+	})
+}
+
+export default {
+	load() {
+		return { files: filedata }
+	}
+}

lib/data/doveadm.data.js

@@ -1,160 +1,8 @@
-import { doveadm_arg_types, doveadm_flag_types, getDoveadmCmdLine } from '../doveadm.js'
-import { getVitepressMd } from '../markdown.js'
-import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js'
-import camelCase from 'camelcase'
-import slugify from '@sindresorhus/slugify'
-
-const doveadm_userargs = {
-	'all-users': {
-		cli: 'A',
-		example: false,
-		type: doveadm_arg_types.BOOL,
-		text: `Apply operation to all users.`
-	},
-	'socket-path': {
-		cli: 'S',
-		example: '/var/run/dovecot/doveadm-server',
-		type: doveadm_arg_types.STRING,
-		text: `Path to doveadm socket.`
-	},
-	user: {
-		cli: 'u',
-		example: 'username',
-		type: doveadm_arg_types.STRING,
-		text: `UID of user to apply operation to.`,
-	},
-}
-
-const doveadm_userfileargs = {
-	/* Hidden from documentation.
-	'trans-flags': {
-		type: doveadm_arg_types.INTEGER,
-		text: `Transaction flags.`
-	},
-	*/
-	'user-file': {
-		cli: 'F',
-		type: doveadm_arg_types.STRING,
-		text: `A filename. If set, fetch usernames from file. One username per line.`
-	},
-}
-
-function typeToString(type) {
-	switch (type) {
-	case doveadm_arg_types.ARRAY:
-		return 'array'
-	case doveadm_arg_types.BOOL:
-		return 'boolean'
-	case doveadm_arg_types.INTEGER:
-		return 'integer'
-	case doveadm_arg_types.STRING:
-		return 'string'
-	case doveadm_arg_types.SEARCH_QUERY:
-		return 'search_query'
-	case doveadm_arg_types.ISTREAM:
-		return 'istream'
-	}
-}
-
-function argToHttpParam(arg) {
-	return arg.split('-').reduce((s, c) =>
-		s + (c.charAt(0).toUpperCase() + c.slice(1)))
-}
-
-async function normalizeDoveadm(doveadm) {
-	const md = await getVitepressMd()
-
-	for (const [k, v] of Object.entries(doveadm)) {
-		if (!v) {
-			delete doveadm[k]
-			continue
-		}
-
-		if (v.flags && (v.flags & doveadm_flag_types.USER)) {
-			v.args = { ...v.args, ...doveadm_userargs }
-		}
-
-		if (v.flags && (v.flags & doveadm_flag_types.USERFILE)) {
-			v.args = { ...v.args, ...doveadm_userfileargs }
-		}
-
-		/* Convert 'man' entry into a markdown link to man page.
-		 * We will add the hash to all URLs for simplicity; for those man
-		 * pages that don't have individual command names, this will just
-		 * be ignored by the browser. */
-		if (v.man) {
-			v.man_link = md.renderInline('[[man,' + v.man + ',' + slugify(k) + ']]')
-		}
-
-		/* Change entries. */
-		for (const k2 of ['added', 'changed', 'deprecated', 'removed']) {
-			if (v[k2]) {
-				const changes = []
-					for (const[k3, v3] of Object.entries(v[k2])) {
-						changes.push({
-							text: v3 ? md.render(v3.trim()) : null,
-							version: md.renderInline('[[' + k2 + ',' + k3 + ']]')
-					})
-				}
-				v[k2] = changes
-			}
-		}
-
-		/* Response values. */
-		if (v.response) {
-			if (v.response.text) {
-				v.response.text = md.render(String(v.response.text))
-			}
-		} else {
-			delete v['response']
-		}
-
-		/* Text Description. */
-		if (v.text) {
-			v.text = md.render(v.text)
-		}
-
-		/* Cmd line arguments. */
-		v.usage = k + (v.args ? ' ' + getDoveadmCmdLine(v.args) : '')
-
-		if (v.args) {
-			const args = []
-			for (const [k2, v2] of Object.entries(v.args)) {
-				if (!v2.hidden) {
-					args.push({
-						/* Undefined examples will resolve to undefined. */
-						cli_only: v2.cli_only,
-						example: v2.example,
-						flag: v2.cli ? '-' + v2.cli : (v2.positional ? k2 : '--' + k2),
-						param: argToHttpParam(k2),
-						type: typeToString(v2.type),
-						text: v2.text ? md.render(v2.text) : null
-					})
-				}
-			}
-			v.args = args
-		}
-		if (!v.args || !v.args.length) {
-			delete v['args']
-		}
-
-		/* HTTP API info. */
-		v.http_cmd = camelCase(k)
-	}
-
-	return {
-		doveadm: normalizeArrayData(
-			doveadm,
-			['tags']
-		),
-		http_api_link: md.renderInline('[[link,doveadm_http_api,HTTP API]]')
-	}
-}
+import { addWatchPaths } from '../utility.js'
+import { loadDoveadm } from '../doveadm.js'
 
 export default addWatchPaths({
 	async load() {
-		return await normalizeDoveadm(
-			structuredClone(loadData('doveadm').doveadm)
-		)
+		return await loadDoveadm()
 	}
 })

lib/data/event_categories.data.js

@@ -1,20 +1,8 @@
-import { getVitepressMd } from '../markdown.js'
-import { addWatchPaths, loadData } from '../utility.js'
-
-async function normalizeEventCategories(categories) {
-	const md = await getVitepressMd()
-
-	for (const [k, v] of Object.entries(categories)) {
-		v.description = md.renderInline(v.description)
-	}
-
-	return categories
-}
+import { loadEventCategories } from '../event_categories.js'
+import { addWatchPaths } from '../utility.js'
 
 export default addWatchPaths({
 	async load() {
-		return await normalizeEventCategories(
-			structuredClone(loadData('event_categories').categories)
-		)
+		return await loadEventCategories()
 	}
 })

lib/data/event_reasons.data.js

@@ -1,20 +1,8 @@
-import { getVitepressMd } from '../markdown.js'
-import { addWatchPaths, loadData } from '../utility.js'
-
-async function normalizeEventReasons(reasons) {
-	const md = await getVitepressMd()
-
-	for (const [k, v] of Object.entries(reasons)) {
-		v.description = md.renderInline(v.description)
-	}
-
-	return reasons
-}
+import { addWatchPaths } from '../utility.js'
+import { loadEventReasons } from '../event_reasons.js'
 
 export default addWatchPaths({
 	async load() {
-		return await normalizeEventReasons(
-			structuredClone(loadData('event_reasons').reasons)
-		)
+		return await loadEventReasons()
 	}
 })