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

Providing static versions of the fully parsed/transformed data files used
to build the documentation may be useful, since it allows things like,
e.g., parsing the settings or doveadm config files for use in automated
coding and tasks.

Author: slusarz

.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/

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/datafiles.js

@@ -0,0 +1,64 @@
+import path from 'path'
+import { lib_dirname } from './utility.js'
+
+const download_base = 'datafiles'
+const github_base = 'https://github.com/dovecot/documentation'
+
+export const publicDataDir = path.resolve(lib_dirname, `../public/${download_base}`)
+
+export const dataFileList = [
+	createEntry(
+		'doveadm.js',
+		async () => {
+		        const { loadDoveadm } = await import(path.resolve(lib_dirname, './doveadm.js'))
+		        return await loadDoveadm()
+		}
+	),
+	createEntry(
+		'event_categories.js',
+		async () => {
+		        const { loadEventCategories } = await import(path.resolve(lib_dirname, './event_categories.js'))
+		        return await loadEventCategories()
+		}
+	),
+	createEntry(
+		'event_reasons.js',
+		async () => {
+			const { loadEventReasons } = await import(path.resolve(lib_dirname, './event_reasons.js'))
+			return await loadEventReasons()
+		}
+	),
+	createEntry(
+		'events.js',
+		async () => {
+		        const { loadEvents } = await import(path.resolve(lib_dirname, './events.js'))
+		        return await loadEvents()
+		}
+	),
+	createEntry(
+		'lua.js',
+		async () => {
+		        const { loadLua } = await import(path.resolve(lib_dirname, './lua.js'))
+		        return await loadLua()
+		}
+	),
+	createEntry(
+		'settings.js',
+		async () => {
+		        const { loadSettings } = await import(path.resolve(lib_dirname, './settings.js'))
+		        return await loadSettings()
+		}
+	)
+]
+
+function createEntry(id, func) {
+	const json = `${path.basename(id, '.js')}.json`
+
+	return {
+		data: func,
+		download: `/${download_base}/${json}`,
+		github: `${github_base}/blob/main/data/${id}`,
+		json: path.resolve(publicDataDir, json),
+		name: json
+	}
+}

lib/dovecot_vitepress_init.js

@@ -1,16 +1,41 @@
+import { dataFileList, publicDataDir } from './datafiles.js'
 import { dovecotMdInit } from './markdown.js'
+import fs from 'fs'
+
+let has_run = false
 
 export default function dovecotVitepressInit() {
 	return {
 		name: 'dovecot-vitepress-init',
 		async configResolved(config) {
-			console.log('\n✅ Config resolved!')
+			/*** Init Dovecot Markdown. ***/
 
 			/* We need to synchronously initialize markdown,
 			 * since we need to pre-populate various internal
 			 * tables (e.g. links). */
 			await dovecotMdInit()
-			console.log('\n✅ Markdown initialized!')
-		},
+			console.log('\n✅ Dovecot Markdown initialized.')
+
+			/*** Create static downloadable data files. ***/
+
+			if (has_run) {
+				return
+			}
+			has_run = true
+
+			/* Clean old data files (if they exist) and prepare directory. */
+			fs.rmSync(publicDataDir, { force: true, recursive: true });
+			fs.mkdirSync(publicDataDir, { recursive: true });
+			console.log(`✅ Data files: Created ${publicDataDir}.`)
+
+			/* Build the data files. */
+			for (const d of dataFileList) {
+				fs.writeFileSync(
+					d.json,
+					JSON.stringify(await d.data(), null, 2)
+				)
+				console.log(`✅ Data files: Generated ${d.json}.`)
+			}
+		}
 	}
 }

lib/utility.js

@@ -7,7 +7,7 @@ import { dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+export const lib_dirname = dirname(__filename);
 
 export function normalizeArrayData(data, keys) {
 	for (const [k, v] of Object.entries(data)) {
@@ -33,9 +33,9 @@ export async function loadData(id) {
 			?? ('../data/' + id + '.js')
 
 		try {
-			dataOb[id] = await import(__dirname + '/' + path)
+			dataOb[id] = await import(lib_dirname + '/' + path)
 		} catch (e) {
-			throw new Error('Unable to import module (' + __dirname + '/' +
+			throw new Error('Unable to import module (' + lib_dirname + '/' +
 				path + '):' + e)
 		}
 	}