functions/partials/typeDocsFor.mjsjavascript
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import * as gulpConfig from '../../gulp.config.mjs'
import { importPeer } from './loadPeer.mjs'
import { loadTypescript } from './tsFor.mjs'
import { removeDirectory } from './removeDirectory.mjs'
import { addToDocsPages } from './addToDocsPages.mjs'
const installHint = 'Install it in your project with: npm install --save-dev typedoc'
/**
* Find the TypeDoc of the project being built (an optional peer dependency, only needed when the docs task is
* enabled) and load it, so projects which do not document TypeScript never need it installed.
* @memberOf module:partials
* @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
* @returns {Promise<Object>} The TypeDoc module.
* @throws {Error} With install instructions when typedoc is not installed.
*/
export const loadTypeDoc = (projectPath = process.cwd()) => importPeer('typedoc', { task: 'docs', installHint, projectPath })
const isSource = fileName => /\.(ts|tsx|mts|cts)$/.test(fileName) && !/\.d\.[cm]?ts$/.test(fileName) && !/\.(test|spec)\./.test(fileName)
const listSources = dirPath => fs.readdirSync(dirPath, { withFileTypes: true })
.filter(entry => entry.isFile() && isSource(entry.name))
.map(entry => path.join(dirPath, entry.name))
// Every folder below dirPath (at any depth), named by its path from dirPath, with the source files directly in it
const listFolders = (dirPath, prefix = '') => fs.readdirSync(dirPath, { withFileTypes: true })
.filter(entry => entry.isDirectory() && entry.name !== 'node_modules')
.flatMap(entry => {
const folderPath = path.join(dirPath, entry.name)
const name = `${prefix}${entry.name}`
return [{ name, path: folderPath, files: listSources(folderPath) }, ...listFolders(folderPath, `${name}/`)]
})
const toIdentifier = fileName => fileName.replace(/[^\w$]+(\w)?/g, (match, letter) => (letter || '').toUpperCase()).replace(/^(\d)/, '_$1')
const toModulePath = filePath => filePath.replace(/\.[cm]?tsx?$/, '').split(path.sep).join('/')
/**
* Describe what a source file exports: whether it has a default export, and whether it has any named exports.
* @memberOf module:partials
* @param {Object} ts - The TypeScript compiler API.
* @param {string} filePath
* @returns {{hasDefault: boolean, hasNamed: boolean}}
*/
export const describeExports = (ts, filePath) => {
const source = ts.createSourceFile(filePath, fs.readFileSync(filePath, 'utf8'), ts.ScriptTarget.Latest)
let hasDefault = false
let hasNamed = false
source.statements.forEach(statement => {
if (ts.isExportAssignment(statement)) {
hasDefault = hasDefault || !statement.isExportEquals
return
}
if (ts.isExportDeclaration(statement)) {
const names = statement.exportClause && ts.isNamedExports(statement.exportClause) ? statement.exportClause.elements : null
if (names && names.some(element => element.name.text === 'default')) {
hasDefault = true
}
if (!names || names.some(element => element.name.text !== 'default')) {
hasNamed = true
}
return
}
const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) || [] : []
if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
hasDefault = true
} else {
hasNamed = true
}
}
})
return { hasDefault, hasNamed }
}
/**
* The description of a folder for its module: the first doc comment of the folder's index file, without its tags
* (@module, @file, ...), or an empty string when there is none.
* @memberOf module:partials
* @param {string} folderPath
* @returns {string}
*/
export const describeFolder = folderPath => {
const indexFile = ['index.ts', 'index.tsx', 'index.mts', 'index.cts'].map(name => path.join(folderPath, name)).find(file => fs.existsSync(file))
return indexFile ? describeFile(indexFile) : ''
}
/**
* The description of a source file for its module: its first doc comment without the tags (@module, @file, ...), when
* that comment is a header (it is followed by an import or export, so it does not document a declaration itself), or
* an empty string.
* @memberOf module:partials
* @param {string} filePath
* @returns {string}
*/
export const describeFile = filePath => {
const comment = fs.readFileSync(filePath, 'utf8').match(/^\s*\/\*\*([\s\S]*?)\*\/\s*(import\b|export\s+(\*|\{[^}]*\}\s+from)|$)/)
if (!comment) {
return ''
}
const lines = comment[1].split('\n').map(line => line.replace(/^\s*\* ?/, '').trimEnd())
const tagAt = lines.findIndex(line => /^@\w+/.test(line))
return (tagAt === -1 ? lines : lines.slice(0, tagAt)).join('\n').trim()
}
/**
* Write one entry file per folder of the source directory into the entry directory. TypeDoc makes a module of every
* entry file, so the modules of the documentation mirror the folders. Nested folders are modules of their own, named
* by their path (utilities/parsers), and a folder's module holds only the files directly in it. The default export of each source file is
* re-exported under the name of the file (the source files hold one function each), and anything else a file exports
* is re-exported as it is (that is where the types.ts files go). Index files (the barrels), tests and declaration
* files are left out, but the first doc comment of a folder's index file becomes the description of its module.
* A file which sits beside the folders (not an index, main or browser file) is a module of its own, described by its header
* comment. A source directory with no folders gets a single entry called index.
* @memberOf module:partials
* @param {Object} ts - The TypeScript compiler API.
* @param {string} srcDir - The directory holding the TypeScript source.
* @param {string} entryDir - The directory to write the entry files into.
* @returns {Array<string>} The paths of the entry files.
*/
export const writeDocEntries = (ts, srcDir, entryDir) => {
const absoluteSrc = path.resolve(srcDir)
fs.mkdirSync(entryDir, { recursive: true })
const folders = listFolders(absoluteSrc).filter(folder => folder.files.some(file => !/^index\./.test(path.basename(file))))
const rootFiles = listSources(absoluteSrc).filter(file => !/^(index|main|browser)\./.test(path.basename(file)))
// Folders make modules, and so do the files which sit beside them (except the barrels: index, main and browser, the
// browser bundle's entry). A source directory with no folders gets a single module called index which holds its files.
const groups = folders.length
? [
...folders,
...rootFiles
.map(file => ({ name: toIdentifier(path.basename(file).replace(/\.[cm]?tsx?$/, '')), files: [file], description: describeFile(file) }))
.filter(group => !folders.some(folder => folder.name === group.name))
]
: [{ name: 'index', path: absoluteSrc, files: rootFiles }]
return groups.map(group => {
const lines = group.files
.filter(file => !/^index\./.test(path.basename(file)))
.sort()
.flatMap(file => {
const modulePath = toModulePath(file)
const { hasDefault, hasNamed } = describeExports(ts, file)
const fileName = path.basename(file).replace(/\.[cm]?tsx?$/, '')
return [
...(hasDefault ? [`export { default as ${toIdentifier(fileName)} } from '${modulePath}'`] : []),
...(hasNamed ? [`export * from '${modulePath}'`] : [])
]
})
const description = group.description ?? (group.path ? describeFolder(group.path) : '')
// TypeDoc takes the first comment of an entry file which has the @module tag as the description of the module
// A nested folder's module is named by its path (utilities/parsers), so it is not mistaken for its parent's
const moduleName = group.name.includes('/') ? ` ${group.name}` : ''
const moduleComment = description || moduleName ? `/**\n${description ? description.split('\n').map(line => ` * ${line}`.trimEnd()).join('\n') + '\n' : ''} * @module${moduleName}\n */\n\n` : ''
const entryPath = path.join(entryDir, `${group.name}.ts`)
fs.mkdirSync(path.dirname(entryPath), { recursive: true })
fs.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n')
return entryPath
})
}
const projectName = () => {
try {
return JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')).name
} catch (error) {
return path.basename(process.cwd())
}
}
/**
* Generate the HTML documentation of a TypeScript project with TypeDoc, straight from the TypeScript source, so the
* types (and the comments on them) are documented from where they are defined. The modules mirror the folders of the
* source, see {@link writeDocEntries}. Configure this with 'docs.from', 'docs.to', 'docs.index', 'docs.title',
* 'docs.tsconfig' and 'docs.logLevel'.
* @memberOf module:partials
* @param {string} [srcPath=gulpConfig.get('docs.from')] - The directory holding the TypeScript source.
* @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
* @param {function(string): Promise<Object>} [loadDocs] - Resolves the TypeDoc module, tests can inject a stand-in.
* @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
*/
export const typeDocsFor = (
srcPath = gulpConfig.get('docs.from'),
outPath = gulpConfig.get('docs.to'),
loadDocs = loadTypeDoc
) => {
if (gulpConfig.get('docs.enabled') === false) {
return () => {}
}
return (done) => {
const generate = async () => {
const ts = loadTypescript()
const { Application } = await loadDocs()
const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'typedocs-'))
try {
const entryPoints = writeDocEntries(ts, srcPath, path.join(workDir, 'entries'))
// The entry files live outside the project, so the tsconfig which is used for the documentation extends the
// one of the project and adds the entries to the files it includes.
const projectConfig = gulpConfig.get('docs.tsconfig') || gulpConfig.get('typescript.config')
const tsconfig = path.join(workDir, 'tsconfig.json')
fs.writeFileSync(tsconfig, JSON.stringify({
...(projectConfig ? { extends: path.resolve(projectConfig) } : {}),
include: [path.join(workDir, 'entries', '**', '*.ts').split(path.sep).join('/'), path.resolve(srcPath).split(path.sep).join('/') + '/**/*.ts'],
exclude: [path.resolve(srcPath).split(path.sep).join('/') + '/**/*.test.*']
}))
const indexFile = gulpConfig.get('docs.index')
const gitRevision = gulpConfig.get('docs.gitRevision')
await removeDirectory(outPath)
const app = await Application.bootstrap({
entryPoints,
tsconfig,
name: gulpConfig.get('docs.title') || projectName(),
readme: indexFile && fs.existsSync(indexFile) ? indexFile : 'none',
logLevel: gulpConfig.get('docs.logLevel') || 'Warn',
skipErrorChecking: true,
// Left out, TypeDoc links each declaration to its source at the current commit, so every commit changes
// every page; a branch name keeps the pages the same until the documentation itself changes.
...(gitRevision ? { gitRevision } : {})
})
const project = await app.convert()
if (!project) {
throw new Error('TypeDoc could not read the TypeScript source, see the errors above.')
}
await app.generateDocs(project, outPath)
addToDocsPages(outPath)
} finally {
await removeDirectory(workDir)
}
}
return typeof done === 'function' ? generate().then(() => done(), done) : generate()
}
}