@appium/docutils 0.1.6 → 0.2.0

package/lib/builder/reference.ts

@@ -0,0 +1,191 @@
+/**
+ * Builds reference documentation via TypeDoc.  The output is _markdown_, intended to be imported into MkDocs.
+ *
+ * @module
+ */
+
+import {fs} from '@appium/support';
+import glob from 'glob';
+import _ from 'lodash';
+import path from 'node:path';
+import {Application, ArgumentsReader, TypeDocOptions, TypeDocReader} from 'typedoc';
+import {
+  DEFAULT_LOG_LEVEL,
+  DEFAULT_REL_TYPEDOC_OUT_PATH,
+  NAME_BIN,
+  NAME_TYPEDOC_JSON,
+} from '../constants';
+import {DocutilsError} from '../error';
+import {findPkgDir, findTypeDocJsonPath, readTypedocJson} from '../fs';
+import logger from '../logger';
+import {argify, relative, stopwatch} from '../util';
+
+const log = logger.withTag('builder:reference');
+
+/**
+ * Replaces TypeDoc's homebrew "glob" implementation with a real one
+ *
+ * This cannot be done via `require('typedoc')` or `import` due to the file being excluded
+ * from the export map in its `package.json`.
+ * @see https://github.com/TypeStrong/typedoc/issues/2151
+ */
+const monkeyPatchTypedoc = _.once(async () => {
+  const typedocDir = await findPkgDir(require.resolve('typedoc'));
+  if (!typedocDir) {
+    throw new DocutilsError('Could not find TypeDoc package directory; is it installed?');
+  }
+  const tdFs = require(path.join(typedocDir, 'dist', 'lib', 'utils', 'fs.js'));
+  tdFs.glob = glob.sync;
+});
+
+/**
+ * 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 async function runTypedoc(typeDocJsonPath: string, opts: Record<string, string>) {
+  await monkeyPatchTypedoc();
+  log.debug('Monkeypatched TypeDoc');
+
+  const args = argify(opts);
+  log.debug('TypeDoc args:', args);
+  const app = new Application();
+  app.options.setValue('plugin', [
+    'typedoc-plugin-markdown',
+    'typedoc-plugin-resolve-crossmodule-references',
+    '@appium/typedoc-plugin-appium',
+  ]);
+  app.options.addReader(new TypeDocReader());
+  app.options.addReader(new ArgumentsReader(100, args));
+  app.bootstrap({options: path.dirname(typeDocJsonPath)});
+  const out = app.options.getValue('out');
+  const project = app.convert();
+  if (project) {
+    return await app.generateDocs(project, out);
+  }
+
+  throw new DocutilsError('TypeDoc found nothing to document. Is your package empty?');
+}
+
+/**
+ * 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
+ */
+type LogLevelName = 'debug' | 'info' | 'error' | 'warn';
+
+/**
+ * Mapping of whatever our log level is to whatever TypeDoc's should be.
+ *
+ * TypeDoc's "info" is too verbose for our needs, and it's our default, so
+ * we map it to "warn".
+ */
+const TypeDocLogLevelMap: Record<LogLevelName, string> = {
+  debug: 'Verbose',
+  info: 'Warn',
+  warn: 'Warn',
+  error: 'Error',
+};
+
+/**
+ * Build reference documentation via TypeDoc
+ * @param opts - Options
+ */
+export async function buildReferenceDocs({
+  typedocJson: typeDocJsonPath,
+  cwd = process.cwd(),
+  tsconfigJson: tsconfig,
+  logLevel = DEFAULT_LOG_LEVEL,
+  title,
+}: BuildReferenceOptions = {}) {
+  const stop = stopwatch('buildReferenceDocs');
+  typeDocJsonPath = typeDocJsonPath
+    ? path.resolve(cwd, typeDocJsonPath)
+    : await findTypeDocJsonPath(cwd);
+  if (!typeDocJsonPath) {
+    throw new DocutilsError(
+      `Could not find ${NAME_TYPEDOC_JSON} from ${cwd}; run "${NAME_BIN}" to create it`
+    );
+  }
+  const pkgRoot = fs.findRoot(cwd);
+  const relativePath = relative(cwd);
+  const relativeTypeDocJsonPath = relativePath(typeDocJsonPath);
+  log.debug(`Using ${relativeTypeDocJsonPath} as typedoc.json`);
+
+  let typeDocJson: Readonly<Partial<TypeDocOptions>>;
+  // we only need typedoc.json to make sure we have a custom "out" path.
+  try {
+    typeDocJson = readTypedocJson(typeDocJsonPath);
+    log.debug('Contents of %s: %O', relativeTypeDocJsonPath, typeDocJson);
+  } catch (err) {
+    log.error(err);
+    throw new DocutilsError(
+      `Could not read ${relativeTypeDocJsonPath}; run "${NAME_BIN} init" to create it`
+    );
+  }
+
+  // if for some reason "out" is not in typedoc.json, we want to use our default path.
+  // otherwise, typedoc's default behavior is to write to the "docs" dir, which is the same dir that
+  // we use (by default) as a source dir for the mkdocs site--which might contain files under vcs.
+  let out: string | undefined;
+  if (typeDocJson.out) {
+    log.debug(`Found "out" option in ${NAME_TYPEDOC_JSON}: ${typeDocJson.out}`);
+  } else {
+    out = path.relative(
+      path.dirname(typeDocJsonPath),
+      path.join(pkgRoot, DEFAULT_REL_TYPEDOC_OUT_PATH)
+    );
+    log.debug('Setting "out" option to %s', out);
+  }
+
+  const extraTypedocOpts = _.pickBy(
+    {tsconfig, name: title, out, logLevel: TypeDocLogLevelMap[logLevel]},
+    Boolean
+  ) as Record<string, string>;
+
+  try {
+    await runTypedoc(typeDocJsonPath, extraTypedocOpts);
+    let finalOut = (typeDocJson.out ?? out) as string;
+    log.success(
+      'Reference docs built at %s (%dms)',
+      path.isAbsolute(finalOut) ? relativePath(finalOut) : finalOut,
+      stop()
+    );
+  } catch (err) {
+    log.error(err);
+  }
+}

package/lib/builder/site.ts

@@ -0,0 +1,143 @@
+/**
+ * Runs `mkdocs`, pulling in reference markdown from TypeDoc and any other documentation from the
+ * `docs_dir` directory (as configured in `mkdocs.yml`).
+ *
+ * @module
+ */
+
+import path from 'node:path';
+import {exec, SubProcess, TeenProcessExecOptions} from 'teen_process';
+import {NAME_BIN, NAME_MKDOCS, NAME_MKDOCS_YML} from '../constants';
+import {DocutilsError} from '../error';
+import {findMkDocsYml, readMkDocsYml, whichMkDocs} from '../fs';
+import logger from '../logger';
+import {relative, stopwatch, TeenProcessSubprocessStartOpts} from '../util';
+
+const log = logger.withTag('mkdocs');
+
+/**
+ * Runs `mkdocs serve`
+ * @param args Extra args to `mkdocs build`
+ * @param opts Extra options for `teen_process.Subprocess.start`
+ * @param mkDocsPath Path to `mkdocs` executable
+ */
+async function doServe(
+  args: string[] = [],
+  {startDetector, detach, timeoutMs}: TeenProcessSubprocessStartOpts = {},
+  mkDocsPath?: string
+) {
+  mkDocsPath = mkDocsPath ?? (await whichMkDocs());
+  const finalArgs = ['serve', ...args];
+  log.debug('Launching %s with args: %O', mkDocsPath, finalArgs);
+  const proc = new SubProcess(mkDocsPath, finalArgs);
+  return await proc.start(startDetector, detach, timeoutMs);
+}
+
+/**
+ * Runs `mkdocs build`
+ * @param args Extra args to `mkdocs build`
+ * @param opts Extra options to `teen_process.exec`
+ * @param mkDocsPath Path to `mkdocs` executable
+ */
+async function doBuild(
+  args: string[] = [],
+  opts: TeenProcessExecOptions = {},
+  mkDocsPath?: string
+) {
+  mkDocsPath = mkDocsPath ?? (await whichMkDocs());
+  const finalArgs = ['build', ...args];
+  log.debug('Launching %s with args: %O', mkDocsPath, finalArgs);
+  return await exec(mkDocsPath, finalArgs, opts);
+}
+
+/**
+ * Runs `mkdocs build` or `mkdocs serve`
+ * @param opts
+ */
+export async function buildSite({
+  mkdocsYml: mkDocsYmlPath,
+  siteDir,
+  theme = NAME_MKDOCS,
+  cwd = process.cwd(),
+  serve = false,
+  serveOpts,
+  execOpts,
+}: BuildMkDocsOpts = {}) {
+  const stop = stopwatch('build-mkdocs');
+  mkDocsYmlPath = mkDocsYmlPath
+    ? path.resolve(process.cwd(), mkDocsYmlPath)
+    : await findMkDocsYml(cwd);
+  if (!mkDocsYmlPath) {
+    throw new DocutilsError(
+      `Could not find ${NAME_MKDOCS_YML} from ${cwd}; run "${NAME_BIN} init" to create it`
+    );
+  }
+  const mkdocsArgs = ['-f', mkDocsYmlPath, '-t', theme];
+  if (siteDir) {
+    mkdocsArgs.push('-d', siteDir);
+  }
+  if (serve) {
+    // unsure about how SIGHUP is handled here
+    await doServe(mkdocsArgs, serveOpts);
+  } else {
+    await doBuild(mkdocsArgs, execOpts);
+    let relSiteDir;
+    if (siteDir) {
+      relSiteDir = relative(cwd, siteDir);
+    } else {
+      ({site_dir: siteDir} = await readMkDocsYml(mkDocsYmlPath));
+      log.debug('Found site_dir %s', siteDir);
+      relSiteDir = relative(path.dirname(mkDocsYmlPath), siteDir!);
+    }
+    log.success('MkDocs finished building into %s (%dms)', relSiteDir, stop());
+  }
+}
+
+/**
+ * Options for {@linkcode buildSite}.
+ */
+export interface BuildMkDocsOpts {
+  /**
+   * Path to `mkdocs.yml`
+   */
+  mkdocsYml?: string;
+
+  /**
+   * Path to output directory
+   */
+  siteDir?: string;
+
+  /**
+   * MkDocs theme to use
+   * @defaultValue 'mkdocs'
+   */
+  theme?: string;
+
+  /**
+   * Current working directory
+   * @defaultValue `process.cwd()`
+   */
+  cwd?: string;
+
+  /**
+   * Path to `package.json`
+   *
+   * Used to find `mkdocs.yml` if unspecified.
+   */
+  packageJson?: string;
+
+  /**
+   * If `true`, run `mkdocs serve` instead of `mkdocs build`
+   */
+  serve?: boolean;
+
+  /**
+   * Extra options for {@linkcode teen_process.exec}
+   */
+  execOpts?: TeenProcessExecOptions;
+
+  /**
+   * Extra options for {@linkcode teen_process.Subprocess.start}
+   */
+  serveOpts?: TeenProcessSubprocessStartOpts;
+}

package/lib/cli/command/build.ts

@@ -0,0 +1,229 @@
+import {CommandModule, InferredOptionTypes, Options} from 'yargs';
+import {buildReferenceDocs, buildSite, deploy, updateNav} from '../../builder';
+import {NAME_BIN} from '../../constants';
+import logger from '../../logger';
+import {stopwatch} from '../../util';
+
+const log = logger.withTag('build');
+
+const NAME_GROUP_BUILD = 'Build Options:';
+const NAME_GROUP_DEPLOY = 'Deployment Options:';
+const NAME_GROUP_SERVE = 'Serve Options:';
+const NAME_GROUP_BUILD_PATHS = 'Paths:';
+
+const opts = {
+  reference: {
+    describe: 'Run TypeDoc command API reference build (Markdown)',
+    group: NAME_GROUP_BUILD,
+    type: 'boolean',
+    default: true,
+  },
+  site: {
+    describe: 'Run MkDocs build (HTML)',
+    group: NAME_GROUP_BUILD,
+    type: 'boolean',
+    default: true,
+  },
+  'site-dir': {
+    alias: 'd',
+    describe: 'HTML output directory',
+    group: NAME_GROUP_BUILD_PATHS,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+    normalize: true,
+    implies: 'site',
+    defaultDescription: '(from mkdocs.yml)',
+  },
+  'package-json': {
+    defaultDescription: './package.json',
+    describe: 'Path to package.json',
+    group: NAME_GROUP_BUILD_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  title: {
+    defaultDescription: '(extension package name)',
+    describe: 'Title of the API reference',
+    group: NAME_GROUP_BUILD,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  'tsconfig-json': {
+    defaultDescription: './tsconfig.json',
+    describe: 'Path to tsconfig.json',
+    group: NAME_GROUP_BUILD_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  'mkdocs-yml': {
+    defaultDescription: './mkdocs.yml',
+    description: 'Path to mkdocs.yml',
+    group: NAME_GROUP_BUILD_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  'typedoc-json': {
+    defaultDescription: './typedoc.json',
+    describe: 'Path to typedoc.json',
+    group: NAME_GROUP_BUILD_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  all: {
+    describe: 'Output all reference docs (not just Appium comands)',
+    group: NAME_GROUP_BUILD,
+    implies: 'site',
+    type: 'boolean',
+  },
+  deploy: {
+    describe: 'Commit HTML output',
+    group: NAME_GROUP_DEPLOY,
+    type: 'boolean',
+    implies: 'site',
+  },
+  push: {
+    describe: 'Push after deploy',
+    group: NAME_GROUP_DEPLOY,
+    type: 'boolean',
+    implies: 'deploy',
+  },
+  branch: {
+    alias: 'b',
+    describe: 'Branch to commit to',
+    implies: 'deploy',
+    group: NAME_GROUP_DEPLOY,
+    type: 'string',
+    requiresArg: true,
+    nargs: 1,
+    defaultDescription: 'gh-pages',
+  },
+  remote: {
+    alias: 'r',
+    describe: 'Remote to push to',
+    implies: ['deploy', 'push'],
+    group: NAME_GROUP_DEPLOY,
+    type: 'string',
+    requiresArg: true,
+    nargs: 1,
+    defaultDescription: 'origin',
+  },
+  prefix: {
+    describe: 'Subdirectory within <branch> to commit to',
+    implies: ['deploy', 'branch'],
+    group: NAME_GROUP_DEPLOY,
+    type: 'string',
+    nargs: 1,
+    requiresArg: true,
+  },
+  message: {
+    alias: 'm',
+    describe: 'Commit message',
+    implies: 'deploy',
+    group: NAME_GROUP_DEPLOY,
+    type: 'string',
+    nargs: 1,
+    requiresArg: true,
+  },
+  'deploy-version': {
+    describe: 'Version (directory) to deploy build to',
+    implies: 'deploy',
+    group: NAME_GROUP_DEPLOY,
+    type: 'string',
+    nargs: 1,
+    requiresArg: true,
+    defaultDescription: '(derived from package.json)',
+  },
+  alias: {
+    describe: 'Alias for the build (e.g., "latest"); triggers alias update',
+    implies: 'deploy',
+    group: NAME_GROUP_DEPLOY,
+    type: 'string',
+    nargs: 1,
+    requiresArg: true,
+    defaultDescription: 'latest',
+  },
+  rebase: {
+    describe: 'Rebase <branch> with remote before deploy',
+    implies: ['deploy', 'branch', 'remote'],
+    group: NAME_GROUP_DEPLOY,
+    type: 'boolean',
+  },
+  serve: {
+    describe: 'Start development server',
+    group: NAME_GROUP_SERVE,
+    type: 'boolean',
+  },
+  port: {
+    alias: 'p',
+    describe: 'Development server port',
+    group: NAME_GROUP_SERVE,
+    type: 'number',
+    defaultDescription: '8000',
+    implies: 'serve',
+    nargs: 1,
+    requiresArg: true,
+  },
+  host: {
+    alias: 'h',
+    describe: 'Development server host',
+    group: NAME_GROUP_SERVE,
+    type: 'string',
+    nargs: 1,
+    requiresArg: true,
+    implies: 'serve',
+    defaultDescription: 'localhost',
+  },
+} as const;
+
+opts as Record<string, Options>;
+type BuildOptions = InferredOptionTypes<typeof opts>;
+
+const buildCommand: CommandModule<{}, BuildOptions> = {
+  command: 'build',
+  describe: 'Build Appium extension documentation',
+  builder: (yargs) =>
+    yargs.options(opts).check((argv) => {
+      // either this method doesn't provide camel-cased props, or the types are wrong.
+      if (argv.deploy === true && argv['site-dir']) {
+        log.error(
+          `--site-dir is unsupported when running "${NAME_BIN} deploy"; use --prefix if needd, but remember that the default behavior is to deploy to the root of the branch (${argv.branch}) instead of a subdirectory`
+        );
+        return false;
+      }
+      return true;
+    }),
+  async handler(args) {
+    const stop = stopwatch('build');
+    log.debug('Build command called with args: %O', args);
+    if (!args.site && !args.reference) {
+      // specifically not a DocUtils error
+      throw new Error(
+        'Cannot use both --no-site (--site=false) and --no-reference (--reference=false)'
+      );
+    }
+    if (args.reference) {
+      await buildReferenceDocs(args);
+    }
+    if (args.site) {
+      await updateNav(args);
+      if (args.deploy) {
+        await deploy(args);
+      } else {
+        await buildSite(args);
+      }
+    }
+    log.success('Done! (total: %dms)', stop());
+  },
+};
+
+export default buildCommand;

package/lib/cli/command/index.ts

@@ -0,0 +1,3 @@
+export {default as init} from './init';
+export {default as validate} from './validate';
+export {default as build} from './build';