@appium/docutils 0.1.6 → 0.2.1

package/build/lib/builder/deploy.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Functions for running `mike`
+ *
+ * @module
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploy = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const teen_process_1 = require("teen_process");
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("../constants");
+const error_1 = require("../error");
+const fs_1 = require("../fs");
+const logger_1 = __importDefault(require("../logger"));
+const util_1 = require("../util");
+const log = logger_1.default.withTag('builder:deploy');
+/**
+ * Runs `mike serve`
+ * @param args Extra args to `mike build`
+ * @param opts Extra options for `teen_process.Subprocess.start`
+ * @param mikePath Path to `mike` executable
+ */
+async function doServe(args = [], { startDetector, detach, timeoutMs } = {}, mikePath) {
+    mikePath = mikePath ?? (await (0, fs_1.whichMike)());
+    const finalArgs = ['serve', ...args];
+    log.debug('Launching %s with args: %O', mikePath, finalArgs);
+    const proc = new teen_process_1.SubProcess(mikePath, finalArgs);
+    return await proc.start(startDetector, detach, timeoutMs);
+}
+/**
+ * Runs `mike build`
+ * @param args Extra args to `mike build`
+ * @param opts Extra options to `teen_process.exec`
+ * @param mikePath Path to `mike` executable
+ */
+async function doDeploy(args = [], opts = {}, mikePath) {
+    mikePath = mikePath ?? (await (0, fs_1.whichMike)());
+    const finalArgs = ['deploy', ...args];
+    log.debug('Launching %s with args: %O', mikePath, finalArgs);
+    return await (0, teen_process_1.exec)(mikePath, finalArgs, opts);
+}
+/**
+ * Derives a deployment version from `package.json`
+ * @param packageJsonPath Path to `package.json` if known
+ * @param cwd Current working directory
+ */
+async function findDeployVersion(packageJsonPath, cwd = process.cwd()) {
+    const { pkg } = await (0, fs_1.readPackageJson)(packageJsonPath ? node_path_1.default.dirname(packageJsonPath) : cwd, true);
+    const version = pkg.version;
+    if (!version) {
+        throw new error_1.DocutilsError('No "version" field found in package.json; please add one or specify a version to deploy');
+    }
+    return version;
+}
+/**
+ * Runs `mike build` or `mike serve`
+ * @param opts Options
+ */
+async function deploy({ mkdocsYml: mkDocsYmlPath, packageJson: packageJsonPath, deployVersion: version, cwd = process.cwd(), serve = false, push = false, branch = constants_1.DEFAULT_DEPLOY_BRANCH, remote = constants_1.DEFAULT_DEPLOY_REMOTE, prefix, message, alias, rebase = true, port = constants_1.DEFAULT_SERVE_PORT, host = constants_1.DEFAULT_SERVE_HOST, serveOpts, execOpts, } = {}) {
+    const stop = (0, util_1.stopwatch)('deploy');
+    mkDocsYmlPath = mkDocsYmlPath ?? (await (0, fs_1.findMkDocsYml)(cwd));
+    if (!mkDocsYmlPath) {
+        throw new error_1.DocutilsError(`Could not find ${constants_1.NAME_MKDOCS_YML} from ${cwd}; run "${constants_1.NAME_BIN} init" to create it`);
+    }
+    version = version ?? (await findDeployVersion(packageJsonPath, cwd));
+    const mikeOpts = {
+        'config-file': mkDocsYmlPath,
+        push,
+        remote,
+        branch,
+        prefix,
+        message,
+        rebase,
+        port,
+        host,
+    };
+    if (serve) {
+        const mikeArgs = [
+            ...(0, util_1.argify)(lodash_1.default.pickBy(mikeOpts, (value) => lodash_1.default.isNumber(value) || Boolean(value))),
+            version,
+        ];
+        if (alias) {
+            mikeArgs.push(alias);
+        }
+        // unsure about how SIGHUP is handled here
+        await doServe(mikeArgs, serveOpts);
+    }
+    else {
+        const mikeArgs = [
+            ...(0, util_1.argify)(lodash_1.default.omitBy(mikeOpts, (value, key) => lodash_1.default.includes(['port', 'host'], key) || (!lodash_1.default.isNumber(value) && !value))),
+            version,
+        ];
+        if (alias) {
+            mikeArgs.push(alias);
+        }
+        await doDeploy(mikeArgs, execOpts);
+        log.success('Mike finished deployment into branch %s (%dms)', branch, stop());
+    }
+}
+exports.deploy = deploy;
+//# sourceMappingURL=deploy.js.map

package/build/lib/builder/deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.js","sourceRoot":"","sources":["../../../lib/builder/deploy.ts"],"names":[],"mappings":"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"}

package/build/lib/builder/index.d.ts

@@ -0,0 +1,5 @@
+export * from './deploy';
+export * from './site';
+export * from './reference';
+export * from './nav';
+//# sourceMappingURL=index.d.ts.map

package/build/lib/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/builder/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC"}

package/build/lib/builder/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./deploy"), exports);
+__exportStar(require("./site"), exports);
+__exportStar(require("./reference"), exports);
+__exportStar(require("./nav"), exports);
+//# sourceMappingURL=index.js.map

package/build/lib/builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/builder/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,yCAAuB;AACvB,8CAA4B;AAC5B,wCAAsB"}

package/build/lib/builder/nav.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Handles updating/adding the `nav` property of `mkdocs.yml`, based on the output of `typedoc`;
+ * specifically, the command documentation generated by `@appium/typedoc-plugin-appium`.
+ *
+ * @module
+ */
+import { MkDocsYmlNav } from '../model';
+/**
+ * Because the `nav` property of `mkdocs.yml` is both a recursive type and a kind of awful one, it's
+ * easier to work with it if we rewrite the data into a flat array of objects. We keep a `keypath`
+ * prop which represents the deep/nested location within the `nav` object.
+ *
+ * @privateRemarks This function is not recursive; instead it loops over a queue of items to process
+ * data, and we append to that queue while processing if needed.
+ * @param nav Contents of the `nav` prop of `mkdocs.yml`
+ * @returns A list of objects, each with a `keypath` property and a `fileOrUrl` property (and maybe
+ * a `name` property)
+ */
+export declare function parseNav(nav: MkDocsYmlNav): ParsedNavData[];
+/**
+ * Update the `nav` property of `mkdocs.yml` with a list of "command" files generated by TypeDoc via
+ * `@appium/typedoc-plugin-appium`.
+ *
+ * To be clear, this function **modifies the MkDocs config file (`mkdocs.yml`) in place**; it is
+ * typically under version control, so if this function makes any changes, you'll want to commit them.
+ * @param opts - Options
+ * @todo implement `dryRun` option
+ */
+export declare function updateNav({ cwd, mkdocsYml: mkDocsYmlPath, typedocJson: typeDocJsonPath, all, dryRun, }?: UpdateNavOpts): Promise<void>;
+/**
+ * Options for {@linkcode updateNav}
+ */
+export interface UpdateNavOpts {
+    /**
+     * Current working directory
+     */
+    cwd?: string;
+    /**
+     * Path to `mkdocs.yml`
+     */
+    mkdocsYml?: string;
+    /**
+     * Path to `package.json`
+     */
+    packageJson?: string;
+    /**
+     * Path to `typedoc.json`
+     */
+    typedocJson?: string;
+    /**
+     * If `true`, do not write any files
+     * @remarks Not yet implemented
+     */
+    dryRun?: boolean;
+    /**
+     * If `true`, add _all_ reference documentation to the navigation config (not just commands)
+     */
+    all?: boolean;
+}
+/**
+ * Used internally by {@linkcode updatedNav}
+ * @see {@linkcode parseNav}
+ */
+interface ParsedNavData {
+    /**
+     * Keypath within `nav` for some file or URL
+     */
+    keypath: string;
+    /**
+     * A filepath (usually) or a URL.
+     * This is considered the "index" of the data, and should be unique within its parent. If it's not
+     * unique, then it will probably end up that way after updating...
+     */
+    fileOrUrl: string;
+    /**
+     * If this file or url has a proper name, this would be it. Most don't.
+     */
+    name?: string;
+}
+export {};
+//# sourceMappingURL=nav.d.ts.map

package/build/lib/builder/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../../../lib/builder/nav.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH,OAAO,EAAY,YAAY,EAAC,MAAM,UAAU,CAAC;AA4BjD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa,EAAE,CA+B3D;AAgJD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,EAC9B,GAAmB,EACnB,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,eAAe,EAC5B,GAAW,EACX,MAAc,GACf,GAAE,aAAkB,iBAwFpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,UAAU,aAAa;IACrB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/build/lib/builder/nav.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Handles updating/adding the `nav` property of `mkdocs.yml`, based on the output of `typedoc`;
+ * specifically, the command documentation generated by `@appium/typedoc-plugin-appium`.
+ *
+ * @module
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateNav = exports.parseNav = void 0;
+const support_1 = require("@appium/support");
+const lodash_1 = __importDefault(require("lodash"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("../constants");
+const error_1 = require("../error");
+const fs_1 = require("../fs");
+const logger_1 = __importDefault(require("../logger"));
+const util_1 = require("../util");
+const log = logger_1.default.withTag('builder:nav');
+/**
+ * Gets a list of `.md` files relative to `docs_dir`
+ * @param targetDir Directory ostensibly containing Markdown files; must be absolute
+ * @param mkDocsDocsDir The path to the `docs_dir` in the `mkdocs.yml` file; must be absolute
+ * @returns List of Markdown files relative to the `docs_dir` in the `mkdocs.yml` file
+ */
+async function findRelativeMarkdownFiles(targetDir, mkDocsDocsDir) {
+    if (!node_path_1.default.isAbsolute(targetDir)) {
+        throw new error_1.DocutilsError(`Expected absolute path, got '${targetDir}'`);
+    }
+    if (!node_path_1.default.isAbsolute(mkDocsDocsDir)) {
+        throw new error_1.DocutilsError(`Expected absolute path, got '${mkDocsDocsDir}'`);
+    }
+    const relDir = node_path_1.default.relative(mkDocsDocsDir, targetDir);
+    const dirEnts = await support_1.fs.readdir(targetDir, { withFileTypes: true });
+    return dirEnts
+        .filter((ent) => ent.isFile() && ent.name.endsWith('.md'))
+        .map((ent) => node_path_1.default.join(relDir, ent.name));
+}
+/**
+ * Because the `nav` property of `mkdocs.yml` is both a recursive type and a kind of awful one, it's
+ * easier to work with it if we rewrite the data into a flat array of objects. We keep a `keypath`
+ * prop which represents the deep/nested location within the `nav` object.
+ *
+ * @privateRemarks This function is not recursive; instead it loops over a queue of items to process
+ * data, and we append to that queue while processing if needed.
+ * @param nav Contents of the `nav` prop of `mkdocs.yml`
+ * @returns A list of objects, each with a `keypath` property and a `fileOrUrl` property (and maybe
+ * a `name` property)
+ */
+function parseNav(nav) {
+    let parsedNav = [];
+    const entries = Object.entries(nav);
+    const queue = [{ entries, keypath: '' }];
+    while (queue.length) {
+        const { entries, keypath } = queue.shift();
+        for (const [key, item] of entries) {
+            if (lodash_1.default.isString(item)) {
+                const navData = {
+                    keypath: keypath ? `${keypath}.${key}` : key,
+                    fileOrUrl: item,
+                };
+                // if the key is not convertible to a number, it's a name
+                // which was manually put there by somebody.
+                if (Number.isNaN(Number(key))) {
+                    navData.name = key;
+                }
+                parsedNav = [...parsedNav, navData];
+            }
+            else if (lodash_1.default.isObject(item)) {
+                const subEntries = Object.entries(item);
+                queue.push({ entries: subEntries, keypath: keypath ? `${keypath}.${key}` : key });
+            }
+        }
+    }
+    return parsedNav;
+}
+exports.parseNav = parseNav;
+/**
+ * Finds all items within the list of parsed nav data which correpsond to the header.  This is
+ * imperfect, as it's possible for the header string to appear in multiple places in the nav, but let's just ignore that until we can't.
+ * @param navData Some parsed nav data
+ * @param header Header name
+ */
+function filterHeaderItems(navData, header) {
+    return lodash_1.default.filter(navData, (item) => lodash_1.default.toPath(item.keypath).includes(header));
+}
+/**
+ *
+ * @param rootHeaderKeypath Root keypath as determined by {@linkcode getRootHeaderKeypath}
+ * @param offset Numeric offset within the array of items for the header
+ * @param data Any parsed nav data found. For new items, this will be `undefined`. If not new, it
+ * may or may not have a `name` prop, and if it does, we want to retain it.
+ * @returns Complete keypath for a nav item beginning with the root keypath
+ */
+function getKeypathForHeaderItem(rootHeaderKeypath, offset, data) {
+    return data?.name
+        ? `${rootHeaderKeypath}.${offset}.${data.name}`
+        : `${rootHeaderKeypath}.${offset}`;
+}
+/**
+ * Compares two sets of nav data and determines if they are different.
+ *
+ * This does not compare the entire `nav` object with a new one; it works per-header
+ * @param newNavData Nav data as computed by {@linkcode getNavItemsForDir} corresponding to a
+ * particular header
+ * @param navData Subset of original nav data as parsed by {@linkcode parseNav}, corresponding to
+ * the same header
+ */
+function navDataDidChange(newNavData, navData) {
+    const diff = lodash_1.default.xorWith(newNavData, navData, (a, b) => a.keypath === b.keypath && a.fileOrUrl === b.fileOrUrl);
+    return !lodash_1.default.isEmpty(diff);
+}
+/**
+ * Find the "root" keypath for a particular header
+ * @param headerItems Some subset of the nav data having keypaths corresponding to `header`
+ * @param header Header string
+ * @returns The keypath up to the header string, inclusive
+ */
+function getRootHeaderKeypath(headerItems, header) {
+    // these are the parts of the keypath of the first item, which will contain the header string. it
+    // dosn't matter whether we pick the first one or any one; they will all contain the same root
+    // keypath by definition.
+    const rootHeaderKeypathParts = lodash_1.default.toPath(lodash_1.default.first(headerItems).keypath);
+    // this is the keypath up to the header string, inclusive.
+    // we append indices or names to this keypath
+    return rootHeaderKeypathParts.slice(0, rootHeaderKeypathParts.indexOf(header) + 1).join('.');
+}
+/**
+ * This examines the `navData` looking for items matching the header string (which _may_ be defined
+ * by `dir`; if `all` is true, we just use the default header, because we will be returning a whole
+ * lot of headers).
+ *
+ *
+ * @param dir Abs path to directory containing markdown files generated by TypeDoc
+ * @param mkDocsDocsDir Configured `docs_dir` or via options
+ * @param navData Nav data parsed by {@linkcode parseNav}
+ * @param all If `true`, process all markdown files, not just commands
+ */
+async function getNavItemsForDir(dir, mkDocsDocsDir, navData, nav, all = false) {
+    let dataChanged = false;
+    const newNavHeaderItems = [];
+    const referenceOutputFilepaths = await findRelativeMarkdownFiles(dir, mkDocsDocsDir);
+    if (!referenceOutputFilepaths.length) {
+        log.warn('No markdown files found in %s; did TypeDoc run?', dir);
+        return { data: [], changed: false };
+    }
+    const navHeader = all ? lodash_1.default.startCase(node_path_1.default.basename(dir)) : constants_1.DEFAULT_NAV_HEADER;
+    const navHeaderItems = filterHeaderItems(navData, navHeader);
+    // if we found items with this header already, we are going
+    // to replace them all wholesale
+    if (navHeaderItems.length) {
+        log.debug('Found %d item(s) in header %s', navHeaderItems.length, navHeader);
+        // we append indices or names to this keypath
+        const rootHeaderKeypath = getRootHeaderKeypath(navHeaderItems, navHeader);
+        for (const fileOrUrl of referenceOutputFilepaths) {
+            let offset = navHeaderItems.findIndex((item) => item.fileOrUrl === fileOrUrl);
+            const newOffset = offset >= 0 ? offset : navHeaderItems.length;
+            const data = navHeaderItems[offset];
+            log.warn(rootHeaderKeypath, newOffset, data);
+            const keypath = getKeypathForHeaderItem(rootHeaderKeypath, newOffset, data);
+            newNavHeaderItems.push({ keypath, fileOrUrl });
+        }
+        // look for any differences between what we have and what's in the file
+        if (navDataDidChange(newNavHeaderItems, navHeaderItems)) {
+            log.debug('Will write new nav data for header %s: %O', navHeader, newNavHeaderItems);
+            dataChanged = true;
+        }
+        else {
+            log.debug('No changes for header %s', navHeader);
+        }
+    }
+    else {
+        log.debug('No items found in header %s', navHeader);
+        let navOffset = nav.length;
+        for (const [idx, newRefFilepath] of referenceOutputFilepaths.entries()) {
+            newNavHeaderItems.push({
+                keypath: `${navOffset}.${navHeader}.${idx}`,
+                fileOrUrl: newRefFilepath,
+            });
+        }
+        log.debug('Will create nav data for header %s', navHeader);
+        dataChanged = true;
+    }
+    return { data: newNavHeaderItems, changed: dataChanged };
+}
+/**
+ * Applies the changes in `newData` to the `mkDocsYml` object.
+ *
+ * **This function mutates `mkDocsYml`.**
+ * @param newData New nav data
+ * @param mkDocsYml Original `mkdocs.yml`
+ */
+function applyNavData(newData, mkDocsYml) {
+    for (const { keypath, fileOrUrl } of newData) {
+        lodash_1.default.set(mkDocsYml, `nav.${keypath}`, fileOrUrl);
+    }
+}
+/**
+ * Update the `nav` property of `mkdocs.yml` with a list of "command" files generated by TypeDoc via
+ * `@appium/typedoc-plugin-appium`.
+ *
+ * To be clear, this function **modifies the MkDocs config file (`mkdocs.yml`) in place**; it is
+ * typically under version control, so if this function makes any changes, you'll want to commit them.
+ * @param opts - Options
+ * @todo implement `dryRun` option
+ */
+async function updateNav({ cwd = process.cwd(), mkdocsYml: mkDocsYmlPath, typedocJson: typeDocJsonPath, all = false, dryRun = false, } = {}) {
+    // we need `mkdocs.yml` to update
+    // and we need `typedoc.json` to know where to look for the command docs
+    [mkDocsYmlPath, typeDocJsonPath] = await Promise.all([
+        mkDocsYmlPath ?? (0, fs_1.findMkDocsYml)(cwd),
+        typeDocJsonPath ?? (0, fs_1.findTypeDocJsonPath)(cwd),
+    ]);
+    if (!mkDocsYmlPath) {
+        throw new error_1.DocutilsError(`Could not find ${constants_1.NAME_MKDOCS_YML} from ${cwd};  run "${constants_1.NAME_BIN} init" to create it`);
+    }
+    if (!typeDocJsonPath) {
+        throw new error_1.DocutilsError(`Could not find ${constants_1.NAME_TYPEDOC_JSON} from ${cwd};  run "${constants_1.NAME_BIN} init" to create it`);
+    }
+    const relativePath = (0, util_1.relative)(cwd);
+    const relMkDocsYmlPath = relativePath(mkDocsYmlPath);
+    const typeDocJson = (0, fs_1.readTypedocJson)(typeDocJsonPath);
+    const mkDocsYml = (await (0, fs_1.readYaml)(mkDocsYmlPath));
+    /**
+     * Absolute path to `typedoc.json`
+     */
+    const absTypeDocJsonPath = node_path_1.default.isAbsolute(typeDocJsonPath)
+        ? typeDocJsonPath
+        : node_path_1.default.resolve(cwd, typeDocJsonPath);
+    /**
+     * Absolute path to TypeDoc's output directory (`out`)
+     */
+    const typeDocOutDir = node_path_1.default.resolve(node_path_1.default.dirname(absTypeDocJsonPath), typeDocJson.out ? typeDocJson.out : constants_1.DEFAULT_REL_TYPEDOC_OUT_PATH);
+    /**
+     * Absolute path to `mkdocs.yml`
+     */
+    const absMkdocsYmlPath = node_path_1.default.isAbsolute(mkDocsYmlPath)
+        ? mkDocsYmlPath
+        : node_path_1.default.resolve(cwd, mkDocsYmlPath);
+    const { docs_dir: docsDir, nav = [] } = mkDocsYml;
+    /**
+     * Absolute path to the directory containing MkDocs input docs
+     */
+    const mkDocsDocsDir = node_path_1.default.resolve(node_path_1.default.dirname(absMkdocsYmlPath), docsDir ?? 'docs');
+    /**
+     * @todo
+     * `commands` is a dirname configurable via the `commandsDir` option added by
+     * `@appium/typedoc-plugin-appium`. this lives in `typedoc.json`, but in order for it to be parsed
+     * using TypeDoc's facilities, we have to load plugins before reading `typedoc.json`, which is
+     * slow. we will probably have to support this in the future, but for now, we can just hardcode it
+     */
+    const dirs = all ? await (0, fs_1.findDirsIn)(typeDocOutDir) : [node_path_1.default.join(typeDocOutDir, 'commands')];
+    let shouldWriteMkDocsYml = false;
+    const navData = parseNav(nav);
+    // this is the thing which will be assigned to the `nav` prop
+    // and thus written to `mkdocs.yml` if there were any changes.
+    // we don't need the `name` prop, since the name is already present in the keypath.
+    const newData = [];
+    for await (const dir of dirs) {
+        const { data, changed } = await getNavItemsForDir(dir, mkDocsDocsDir, navData, nav, all);
+        if (changed) {
+            shouldWriteMkDocsYml = true;
+        }
+        newData.push(...data);
+    }
+    if (shouldWriteMkDocsYml) {
+        applyNavData(newData, mkDocsYml);
+        const yaml = (0, fs_1.stringifyYaml)(mkDocsYml);
+        log.debug('Writing to %s:\n%s', mkDocsYmlPath, yaml);
+        await (0, fs_1.safeWriteFile)(mkDocsYmlPath, yaml, true);
+        log.success('Updated MkDocs navigation config for reference docs; please run "git add -A %s" and commit this change', relMkDocsYmlPath);
+    }
+    else {
+        log.info('No changes needed for MkDocs config at %s', relMkDocsYmlPath);
+    }
+}
+exports.updateNav = updateNav;
+//# sourceMappingURL=nav.js.map

package/build/lib/builder/nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.js","sourceRoot":"","sources":["../../../lib/builder/nav.ts"],"names":[],"mappings":"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"}

package/build/lib/builder/reference.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Builds reference documentation via TypeDoc.  The output is _markdown_, intended to be imported into MkDocs.
+ *
+ * @module
+ */
+/**
+ * Executes TypeDoc _in the current process_
+ *
+ * You will probably want to run `updateNav()` after this.
+ *
+ * @privateRemarks Monkeypatches TypeDoc's homebrew "glob" implementation because it is broken
+ * @parma typeDocJsonPath - Path to `typedoc.json`
+ * @param opts - TypeDoc options
+ */
+export declare function runTypedoc(typeDocJsonPath: string, opts: Record<string, string>): Promise<void>;
+/**
+ * Options for {@linkcode buildReferenceDocs}
+ */
+export interface BuildReferenceOptions {
+    /**
+     * Path to `typedoc.json`
+     */
+    typedocJson?: string;
+    /**
+     * Current working directory
+     */
+    cwd?: string;
+    /**
+     * Path to `package.json`
+     */
+    packageJson?: string;
+    /**
+     * Path to `tsconfig.json`
+     */
+    tsconfigJson?: string;
+    /**
+     * "Title" for generated docs; this corresponds to {@linkcode typedoc.TypeDocOptionMap.name}
+     */
+    title?: string;
+    /**
+     * This is here because we pass it thru to TypeDoc
+     */
+    logLevel?: LogLevelName;
+}
+/**
+ * Log level names as supported by this package
+ *
+ * Used to convert our log level to TypeDoc's
+ */
+declare type LogLevelName = 'debug' | 'info' | 'error' | 'warn';
+/**
+ * Build reference documentation via TypeDoc
+ * @param opts - Options
+ */
+export declare function buildReferenceDocs({ typedocJson: typeDocJsonPath, cwd, tsconfigJson: tsconfig, logLevel, title, }?: BuildReferenceOptions): Promise<void>;
+export {};
+//# sourceMappingURL=reference.d.ts.map

package/build/lib/builder/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../lib/builder/reference.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoCH;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,iBAsBrF;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;GAIG;AACH,aAAK,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAexD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,WAAW,EAAE,eAAe,EAC5B,GAAmB,EACnB,YAAY,EAAE,QAAQ,EACtB,QAA4B,EAC5B,KAAK,GACN,GAAE,qBAA0B,iBAyD5B"}