@appium/docutils 0.4.12 → 1.0.1

package/lib/builder/reference.ts

@@ -1,171 +0,0 @@
-/**
- * Builds reference documentation via TypeDoc.  The output is _markdown_, intended to be imported into MkDocs.
- *
- * @module
- */
-
-import {fs} from '@appium/support';
-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 {findTypeDocJsonPath, readTypedocJson} from '../fs';
-import {getLogger} from '../logger';
-import {argify, relative, stopwatch} from '../util';
-
-const log = getLogger('builder:reference');
-
-/**
- * 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>) {
-  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);
-    const 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/mike.js

@@ -1,153 +0,0 @@
-/**
- * API around `mike`, a tool for deploying multiple versions of MkDocs-built sites to GitHub Pages
- * @module
- */
-
-import {exec} from 'teen_process';
-// eslint-disable-next-line import/no-unresolved
-import log from './logger';
-
-const DEFAULT_REMOTE = 'origin';
-const DEFAULT_BRANCH = 'gh-pages';
-const MIKE_VER_STRING = 'mike 1.';
-
-/**
- * @deprecated Use the `deploy` export from `@appium/docutils`
- */
-export class Mike {
-  /** @type {string} */ remote;
-  /** @type {string} */ branch;
-  /** @type {string?} */ prefix;
-  /** @type {string} */ configFile;
-  /** @type {boolean} */ _mikeVerified = false;
-
-  constructor(/** @type MikeOpts */ opts) {
-    this.remote = opts.remote || DEFAULT_REMOTE;
-    this.branch = opts.branch || DEFAULT_BRANCH;
-    this.prefix = opts.prefix;
-    this.configFile = opts.configFile;
-  }
-
-  /**
-   * Throw an error if the 'mike' binary cannot be found
-   *
-   * @throws {Error}
-   */
-  async verifyMike() {
-    if (this._mikeVerified) {
-      return;
-    }
-    try {
-      const {stdout} = await this.exec('--version', [], false);
-      if (!stdout.includes(MIKE_VER_STRING)) {
-        throw new Error('Mike was installed but was not version 1.x');
-      }
-    } catch (err) {
-      throw new Error(`Could not verify appropriate mike binary exists: ${err}`);
-    }
-    this._mikeVerified = true;
-  }
-
-  /**
-   * Get an array of args based on the class members that can be used with Mike-related subprocess
-   * execution
-   *
-   * @param {string} cmdName - the name of the mike command to run
-   * @param {string[]} cmdArgs - an array of command-specific arguments
-   *
-   * @returns {string[]}
-   */
-  getMikeArgs(cmdName, cmdArgs) {
-    return [
-      cmdName,
-      ...cmdArgs,
-      '--config-file',
-      this.configFile,
-      '--remote',
-      this.remote,
-      '--branch',
-      this.branch,
-      '--prefix',
-      this.prefix,
-    ];
-  }
-
-  /**
-   * Exec mike as a subprocess
-   *
-   * @param {string} mikeCmd - the mike command to run
-   * @param {string[]} [mikeArgs=[]] - the arguments to pass to the mike command
-   * @param {boolean?} [verify=true] - whether to verify mike exists first
-   *
-   * @returns {Promise<import('teen_process').ExecResult<string>>}
-   */
-  async exec(mikeCmd, mikeArgs = [], verify = true) {
-    if (verify) {
-      await this.verifyMike();
-    }
-    const args = this.getMikeArgs(mikeCmd, mikeArgs);
-    log.debug(`Running mike ${args.join(' ')}`);
-    return await exec('mike', args);
-  }
-
-  /**
-   * Return the list of mike deploys
-   *
-   * @returns {string[]}
-   */
-  async list() {
-    const {stdout} = await this.exec('list');
-    return stdout
-      .split('\n')
-      .map((s) => s.trim())
-      .filter(Boolean);
-  }
-
-  /**
-   * Set the default version or alias
-   *
-   * @param {string} alias - the version or alias
-   */
-  async setDefault(alias) {
-    await this.exec('set-default', [alias]);
-  }
-
-  /**
-   * Deploy docs to the branch
-   *
-   * @param {MikeDeployOpts} opts - the deploy options
-   */
-  async deploy(opts) {
-    const args = [opts.version];
-    if (opts.alias) {
-      args.push(opts.alias, '--update-aliases');
-    }
-    if (opts.shouldPush) {
-      args.push('--push');
-    }
-    if (opts.shouldRebase) {
-      args.push('--rebase');
-    }
-    if (opts.commit) {
-      args.push('--message', opts.commit);
-    }
-    await this.exec('deploy', args);
-  }
-}
-
-/**
- * @typedef MikeOpts - options for instantiating a Mike object
- * @property {string} [remote="origin"] - the git remote to push docs to
- * @property {string} [branch="gh-pages"] - the git branch to push docs to
- * @property {string?} prefix - the path prefix on the branch if any
- * @property {string} configFile - the mkdocs config file to use
- */
-
-/**
- * @typedef MikeDeployOpts - options for deploying docs with Mike
- * @param {string} version - the version to deploy
- * @param {string?} alias - the alias to alias (or re-alias) the version
- * @param {string?} commit - the commit message to use as an override
- * @param {boolean?} shouldPush - whether mike should push the commits to the remote
- * @param {boolean?} shouldRebase - whether mike should rebase
- */