build-api-docs.mjs

// @ts-check
import fs from 'fs'
import path from 'path'
import {r, escape} from 'regexr'
import {CommentAnalyzer, MarkdownRenderer} from 'readem'

/** Check if a file exists.
 * @param {string} filePath
 * @returns {Promise<boolean>}
 */
async function fileExists(filePath) {
	try {
		await fs.promises.access(filePath, fs.constants.F_OK)
		return true
	} catch (e) {
		return false
	}
}

async function main() {
	const docsMeta = await new CommentAnalyzer().analyze('./node_modules/lume/src', file => {
		// Ignore lib files that we copied into the repo.
		return !file.startsWith('./src/lib/')
	})
	const renderer = new MarkdownRenderer()

	await renderer.render(docsMeta, './api/')

	const navMarkdown = renderer
		.renderNav(docsMeta, {linePadStart: '  ', basePath: path.sep + 'api'})
		.split('\n')
		// Unindent the nav markdown.
		.map(line => '  ' + line.trimLeft())
		// If Windows, replace backslash with slash (move into readem?)
		.map(line => line.replaceAll('\\', '/'))
		.join('\n')

	const sidebarFile = path.resolve('.', '_sidebar.src.md')

	/** @type {string} */
	const startMarker = escape('<!-- __API_AUTOGENERATED_BEGIN__ -->')
	/** @type {string} */
	const endMarker = escape('<!-- __API_AUTOGENERATED_END__ -->')

	let content = (await fileExists(sidebarFile))
		? await fs.promises.readFile(sidebarFile, {encoding: 'utf8'})
		: startMarker + endMarker

	content = content.replace(
		r`${startMarker}(\s|\S)*${endMarker}`,
		`${startMarker}
${navMarkdown}
${endMarker}`,
	)

	await fs.promises.writeFile(sidebarFile.replace('.src.md', '.md'), content, {encoding: 'utf8'})
}

main().catch(e => {
	// Make sure the process exits with a non-zero exit code on unhandle promise
	// rejections. This won't be necessary in an upcoming release of Node.js, in
	// which case it'll exit non-zero automatically. Time of writing this comment:
	// Node 13.8.
	console.error(e)
	process.exit(1)
})