functions/partials/jsdocDocsFor.mjsjavascript
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import { createRequire } from 'node:module'
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
import * as gulpConfig from '../../gulp.config.mjs'
import { removeDirectory } from './removeDirectory.mjs'
import { addToDocsPages } from './addToDocsPages.mjs'
const execFileAsync = promisify(execFile)
const escapeHtml = text => String(text).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"')
const jsdocInstallHint = 'Install it in your project with: npm install --save-dev jsdoc'
const themeInstallHint = name => `Install it in your project with: npm install --save-dev ${name}`
/**
* Resolve the installed directory of an optional peer dependency, from the project being built rather than from
* this package. Deliberately not requirePeer/importPeer's own `require(name + '/package.json')` approach - that
* breaks for any package whose own package.json restricts its exports map and does not expose that subpath
* (clean-jsdoc-theme does; confirmed live, not assumed - resolving its own package.json throws
* ERR_PACKAGE_PATH_NOT_EXPORTED in plain Node, and a differently-shaped MODULE_NOT_FOUND under Jest's own
* resolver, which still is not "not installed" either way). Walking Node's own real module-lookup directories
* (require.resolve.paths) and checking each on disk sidesteps the exports map entirely - this only ever reads
* whether `<dir>/<name>/package.json` exists, never asks the module system to resolve a restricted subpath.
* @memberOf module:partials
* @param {string} name - The package name.
* @param {Object} options
* @param {string} options.task
* @param {string} options.installHint
* @param {string} [options.projectPath=process.cwd()]
* @returns {string}
* @throws {Error} With install instructions when the package is not installed.
*/
const resolvePeerDir = (name, { task, installHint, projectPath = process.cwd() }) => {
const req = createRequire(path.join(projectPath, 'package.json'))
const found = (req.resolve.paths(name) || [])
.map(dir => path.join(dir, name))
.find(dir => fs.existsSync(path.join(dir, 'package.json')))
if (!found) {
throw new Error(`The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`)
}
return found
}
/**
* Resolve jsdoc's own CLI entry point. jsdoc has no stable programmatic Node API for generating HTML docs (unlike
* TypeDoc's Application.bootstrap()/convert()/generateDocs()) - gulp-jsdoc3, the established gulp wrapper, is
* stale, and its own README admits jsdoc does not support piped input in the first place, a real anti-pattern for
* this project's own gulp-stream conventions. Running its real CLI via child_process is the portable way in -
* confirmed via `npm view jsdoc bin`, which reports "jsdoc.js" at the package root.
* @memberOf module:partials
* @param {string} [projectPath=process.cwd()]
* @returns {string}
*/
export const resolveJsdocBin = (projectPath = process.cwd()) =>
path.join(resolvePeerDir('jsdoc', { task: 'docs', installHint: jsdocInstallHint, projectPath }), 'jsdoc.js')
/**
* Resolve a jsdoc theme package's own template directory, for jsdoc's own opts.template config key: the folder
* holding its publish.js. That is the package root for a classic jsdoc template (clean-jsdoc-theme 4.x included),
* but `dist` for a bundled one (clean-jsdoc-theme 5.x).
* @memberOf module:partials
* @param {string} name
* @param {string} [projectPath=process.cwd()]
* @returns {string}
*/
export const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
const packageDir = resolvePeerDir(name, { task: 'docs', installHint: themeInstallHint(name), projectPath })
const distDir = path.join(packageDir, 'dist')
return fs.existsSync(path.join(distDir, 'publish.js')) ? distDir : packageDir
}
/**
* Generate the HTML documentation of a plain-JavaScript project with jsdoc, using jsdoc.base.js's own shared
* config (plugins, includePattern/excludePattern) as the starting point rather than a parallel one - the same
* base a project's own .jsdoc.conf.js has always been able to extend, just with source.include and the output
* options generated here instead of hand-maintained per project. Configure this with 'docs.from', 'docs.to',
* 'docs.index', 'docs.theme' and 'docs.title'.
* @memberOf module:partials
* @param {string|Array<string>} [srcPath=gulpConfig.get('docs.from')] - The directory (or directories and files) holding
* the JS source.
* @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
* @param {function(string, Array<string>): Promise<Object>} [runJsdoc] - Runs the jsdoc CLI, tests can inject a stand-in.
* @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
*/
export const jsdocDocsFor = (
srcPath = gulpConfig.get('docs.from'),
outPath = gulpConfig.get('docs.to'),
runJsdoc = (bin, args) => execFileAsync(process.execPath, [bin, ...args])
) => {
if (gulpConfig.get('docs.enabled') === false) {
return () => {}
}
return (done) => {
const generate = async () => {
const theme = gulpConfig.get('docs.theme') || 'clean-jsdoc-theme'
const themeDir = resolveJsdocTheme(theme)
const indexFile = gulpConfig.get('docs.index')
const title = gulpConfig.get('docs.title')
const basePath = gulpConfig.get('docs.basePath')
await removeDirectory(outPath)
const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsdocdocs-'))
// clean-jsdoc-theme 5.x writes no index.html at all without a front page, so fall back to one with the title
let readme = indexFile && fs.existsSync(indexFile) ? path.resolve(indexFile) : ''
if (!readme) {
readme = path.join(workDir, 'index.md')
fs.writeFileSync(readme, `# ${title || 'Documentation'}\n`)
}
// Loaded here, not at the top: jsdoc.base.js reads the gulp config as soon as it loads (at the top, Jest's
// native ES module mode hit a require(esm) cycle through gulp.config.js). It's CommonJS (consuming projects'
// .jsdoc.conf.js require it directly); import() gives its module.exports as the default export.
const { default: jsdocBase } = await import('../../jsdoc.base.js')
const config = {
...jsdocBase,
source: {
...jsdocBase.source,
include: [].concat(srcPath).map(includePath => path.resolve(includePath))
},
opts: {
destination: path.resolve(outPath),
// jsdoc does not recurse into source.include's own subdirectories by default - without this, only
// the top level of docs.from would ever be scanned. Confirmed from clean-jsdoc-theme's own README
// quick-start example, which sets this explicitly, not assumed from jsdoc's own classic defaults.
recurse: true,
template: themeDir,
// clean-jsdoc-theme 4.x's own options for the name in its header and the home page's <title> (otherwise "Home").
// The header is given as a link: a plain-text title links to the site root ("/"), while every page is in one
// folder, so index.html is the home page wherever they are served. Both are printed unescaped by the theme.
// clean-jsdoc-theme 5.x reads its options from opts itself: the name in its header and <title>, and the path
// its root-absolute links start from (4.x reads only theme_opts).
...(title ? { siteName: title } : {}),
...(basePath ? { basePath } : {}),
...(title
? {
theme_opts: {
title: `<a href="index.html" class="sidebar-title sidebar-title-anchor">${escapeHtml(title)}</a>`,
homepageTitle: escapeHtml(title)
}
}
: {}),
readme
}
}
try {
const configPath = path.join(workDir, 'jsdoc.conf.json')
fs.writeFileSync(configPath, JSON.stringify(config))
const bin = resolveJsdocBin()
// Pass on what jsdoc and the theme report (warnings such as a page which failed to render), which would
// otherwise be lost with the captured output
const { stdout = '', stderr = '' } = (await runJsdoc(bin, ['-c', configPath])) || {}
const report = `${stdout}${stderr}`.trim()
if (report) {
console.warn(report)
}
addToDocsPages(outPath)
} finally {
await removeDirectory(workDir)
}
}
return typeof done === 'function' ? generate().then(() => done(), done) : generate()
}
}