@appium/docutils 0.4.12 → 1.0.1

package/lib/cli/command/build.ts

@@ -5,7 +5,7 @@
 
 import path from 'node:path';
 import type {CommandModule, InferredOptionTypes, Options} from 'yargs';
-import {buildReferenceDocs, buildSite, deploy, updateNav} from '../../builder';
+import {buildSite, deploy} from '../../builder';
 import {NAME_BIN} from '../../constants';
 import {getLogger} from '../../logger';
 import {stopwatch} from '../../util';
@@ -21,12 +21,6 @@ enum BuildCommandGroup {
 }
 
 const opts = {
-  reference: {
-    describe: 'Run TypeDoc command API reference build (Markdown)',
-    group: BuildCommandGroup.Build,
-    type: 'boolean',
-    default: true,
-  },
   site: {
     describe: 'Run MkDocs build (HTML)',
     group: BuildCommandGroup.Build,
@@ -55,24 +49,6 @@ const opts = {
     requiresArg: true,
     type: 'string',
   },
-  title: {
-    defaultDescription: '(extension package name)',
-    describe: 'Title of the API reference',
-    group: BuildCommandGroup.Build,
-    nargs: 1,
-    requiresArg: true,
-    type: 'string',
-  },
-  'tsconfig-json': {
-    defaultDescription: './tsconfig.json',
-    describe: 'Path to tsconfig.json',
-    group: BuildCommandGroup.BuildPaths,
-    nargs: 1,
-    normalize: true,
-    requiresArg: true,
-    coerce: path.resolve,
-    type: 'string',
-  },
   'mkdocs-yml': {
     defaultDescription: './mkdocs.yml',
     description: 'Path to mkdocs.yml',
@@ -83,22 +59,6 @@ const opts = {
     coerce: path.resolve,
     type: 'string',
   },
-  'typedoc-json': {
-    defaultDescription: './typedoc.json',
-    describe: 'Path to typedoc.json',
-    group: BuildCommandGroup.BuildPaths,
-    nargs: 1,
-    normalize: true,
-    requiresArg: true,
-    coerce: path.resolve,
-    type: 'string',
-  },
-  all: {
-    describe: 'Output all reference docs (not just Appium comands)',
-    group: BuildCommandGroup.Build,
-    implies: 'site',
-    type: 'boolean',
-  },
   deploy: {
     describe: 'Commit HTML output to a branch using mike',
     group: BuildCommandGroup.Deploy,
@@ -131,7 +91,7 @@ const opts = {
     nargs: 1,
     defaultDescription: 'origin',
   },
-  prefix: {
+  'deploy-prefix': {
     describe: 'Subdirectory within <branch> to commit to',
     implies: 'branch',
     group: BuildCommandGroup.Deploy,
@@ -166,12 +126,15 @@ const opts = {
     requiresArg: true,
     defaultDescription: 'latest',
   },
-  rebase: {
-    describe: 'Rebase <branch> with remote before deploy',
+  'alias-type': {
+    describe: 'Alias creation strategy',
     implies: 'deploy',
     group: BuildCommandGroup.Deploy,
-    type: 'boolean',
-    defaultDescription: 'true',
+    type: 'string',
+    nargs: 1,
+    requiresArg: true,
+    choices: ['symlink', 'redirect', 'copy'],
+    defaultDescription: 'redirect',
   },
   serve: {
     describe: 'Start development server',
@@ -204,37 +167,27 @@ type BuildOptions = InferredOptionTypes<typeof opts>;
 
 export default {
   command: 'build',
-  describe: 'Build Appium extension documentation using TypeDoc & MkDocs',
+  describe: 'Build Appium extension documentation using MkDocs',
   builder(yargs) {
     return yargs
       .options(opts)
       .check(async (argv) => {
         // either this method doesn't provide camel-cased props, or the types are wrong.
         if (argv.deploy === true && argv['site-dir']) {
-          return `--site-dir is unsupported when running "${NAME_BIN} deploy"; use --prefix if needed, but remember that the default behavior is to deploy to the root of the branch (${argv.branch}) instead of a subdirectory`;
+          return `--site-dir is unsupported when running "${NAME_BIN} deploy"; use --deploy-prefix if needed, but remember that the default behavior is to deploy to the root of the branch (${argv.branch}) instead of a subdirectory`;
         }
 
         return await checkMissingPaths(opts, BuildCommandGroup.BuildPaths, argv);
       })
       .epilog(
-        'For help with further configuration, see:\n  - MkDocs: https://www.mkdocs.org\n  - TypeDoc: https://typedoc.org\n  - Mike: https://github.com/jimporter/mike'
+        'For help with further configuration, see:\n  - MkDocs: https://www.mkdocs.org\n  - Mike: https://github.com/jimporter/mike',
       );
   },
   async handler(args) {
     log.info('Building docs...');
     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 {

package/lib/cli/command/init.ts

@@ -149,33 +149,6 @@ const opts = {
     type: 'string',
     implies: 'typescript',
   },
-  typedoc: {
-    default: true,
-    description: 'Create typedoc.json if needed',
-    group: InitCommandGroup.Behavior,
-    type: 'boolean',
-    implies: 'entry-point',
-  },
-  'typedoc-json': {
-    defaultDescription: './typedoc.json',
-    describe: 'Path to new or existing typedoc.json',
-    group: InitCommandGroup.Behavior,
-    nargs: 1,
-    normalize: true,
-    requiresArg: true,
-    type: 'string',
-    implies: 'typedoc',
-  },
-  'entry-point': {
-    alias: 'e',
-    describe: 'Source entry point of extension',
-    group: InitCommandGroup.Paths,
-    nargs: 1,
-    normalize: false,
-    requiresArg: true,
-    type: 'string',
-    implies: 'typedoc',
-  },
   typescript: {
     default: true,
     description: 'Create tsconfig.json if needed',

package/lib/cli/command/validate.ts

@@ -66,30 +66,6 @@ const opts = {
     requiresArg: true,
     type: 'string',
   },
-  typedoc: {
-    default: true,
-    description: 'Validate TypoDoc environment',
-    group: ValidateCommandGroup.Behavior,
-    type: 'boolean',
-  },
-  'typedoc-json': {
-    defaultDescription: './typedoc.json',
-    describe: 'Path to typedoc.json',
-    group: ValidateCommandGroup.Paths,
-    nargs: 1,
-    normalize: true,
-    requiresArg: true,
-    type: 'string',
-  },
-  'typedoc-path': {
-    defaultDescription: '(derived from shell)',
-    description: 'Path to typedoc executable',
-    group: ValidateCommandGroup.Paths,
-    nargs: 1,
-    normalize: true,
-    requiresArg: true,
-    type: 'string',
-  },
   typescript: {
     default: true,
     description: 'Validate TypeScript environment',
@@ -105,8 +81,8 @@ export default {
   describe: 'Validate Environment',
   builder(yargs) {
     return yargs.options(opts).check(async (argv) => {
-      if (!argv.python && !argv.typedoc && !argv.typescript && !argv.mkdocs) {
-        return 'No validation targets specified; one or more of --python, --typescript, --typedoc or --mkdocs must be provided';
+      if (!argv.python && !argv.typescript && !argv.mkdocs) {
+        return 'No validation targets specified; one or more of --python, --typescript or --mkdocs must be provided';
       }
       return checkMissingPaths(opts, ValidateCommandGroup.Paths, argv);
     });
@@ -131,7 +107,7 @@ export default {
 
     if (errorCount) {
       throw new DocutilsError(
-        `Validation failed with ${errorCount} ${util.pluralize('error', errorCount)}`
+        `Validation failed with ${errorCount} ${util.pluralize('error', errorCount)}`,
       );
     }
   },

package/lib/constants.ts

@@ -26,10 +26,6 @@ export const NAME_TSCONFIG_JSON = 'tsconfig.json';
  * `python` executable
  */
 export const NAME_PYTHON = 'python';
-/**
- * Default name of the `typedoc.json` config file
- */
-export const NAME_TYPEDOC_JSON = 'typedoc.json';
 /**
  * It's `package.json`!
  */
@@ -53,11 +49,6 @@ export const NAME_MKDOCS = 'mkdocs';
  */
 export const NAME_MIKE = 'mike';
 
-/**
- * Name of the `typedoc` executable
- */
-export const NAME_TYPEDOC = 'typedoc';
-
 /**
  * Name of the `pip` module.
  *
@@ -104,7 +95,7 @@ export const PKG_ROOT_DIR = fs.findRoot(__dirname);
  */
 
 export const DOCUTILS_PKG: PackageJson = JSON.parse(
-  readFileSync(path.join(PKG_ROOT_DIR, NAME_PACKAGE_JSON), 'utf8')
+  readFileSync(path.join(PKG_ROOT_DIR, NAME_PACKAGE_JSON), 'utf8'),
 );
 
 /**
@@ -114,9 +105,10 @@ export const DOCUTILS_PKG: PackageJson = JSON.parse(
 export const REQUIREMENTS_TXT_PATH = path.join(PKG_ROOT_DIR, NAME_REQUIREMENTS_TXT);
 
 /**
- * The default output path for Typedoc, computed relative to the consuming package's root
+ * The default alias creation strategy to pass to `mike` when deploying
+ * (`symlink`, `redirect` or `copy`)
  */
-export const DEFAULT_REL_TYPEDOC_OUT_PATH = path.join('docs', 'reference');
+export const DEFAULT_DEPLOY_ALIAS_TYPE = 'redirect';
 
 /**
  * The default branch to deploy to
@@ -149,11 +141,6 @@ export const LogLevelMap = {
   debug: LogLevel.Debug,
 } as const;
 
-/**
- * Default site nav header text
- */
-export const DEFAULT_NAV_HEADER = 'Reference';
-
 /**
  * If the user does not specify a site directory _and_ the `mkdocs.yml` doesn't either, use this dir.
  */

package/lib/fs.ts

@@ -4,28 +4,18 @@
  */
 
 import {fs} from '@appium/support';
-import findUp from 'find-up';
 import * as JSON5 from 'json5';
 import _ from 'lodash';
 import path from 'node:path';
 import _pkgDir from 'pkg-dir';
 import readPkg, {NormalizedPackageJson, PackageJson} from 'read-pkg';
 import {JsonValue} from 'type-fest';
-import {Application, TypeDocReader} from 'typedoc';
 import YAML from 'yaml';
-import {
-  NAME_MIKE,
-  NAME_MKDOCS_YML,
-  NAME_NPM,
-  NAME_PACKAGE_JSON,
-  NAME_PYTHON,
-  NAME_TYPEDOC,
-  NAME_TYPEDOC_JSON,
-} from './constants';
+import {NAME_MIKE, NAME_MKDOCS_YML, NAME_NPM, NAME_PACKAGE_JSON, NAME_PYTHON} from './constants';
 import {DocutilsError} from './error';
 import {getLogger} from './logger';
 import {MkDocsYml} from './model';
-import { exec } from 'teen_process';
+import {exec} from 'teen_process';
 
 const log = getLogger('fs');
 
@@ -44,7 +34,7 @@ export const findPkgDir = _.memoize(_pkgDir);
 export const stringifyYaml: (value: JsonValue) => string = _.partialRight(
   YAML.stringify,
   {indent: 2},
-  undefined
+  undefined,
 );
 
 /**
@@ -65,17 +55,17 @@ export const stringifyJson5: (value: JsonValue) => string = _.partialRight(JSON5
 export const stringifyJson: (value: JsonValue) => string = _.partialRight(
   JSON.stringify,
   2,
-  undefined
+  undefined,
 );
 
 /**
  * Reads a YAML file, parses it and caches the result
  */
-export const readYaml = _.memoize(async (filepath: string) =>
+const readYaml = _.memoize(async (filepath: string) =>
   YAML.parse(await fs.readFile(filepath, 'utf8'), {
     prettyErrors: false,
     logLevel: 'silent',
-  })
+  }),
 );
 
 /**
@@ -87,7 +77,7 @@ export const readYaml = _.memoize(async (filepath: string) =>
  */
 export async function findInPkgDir(
   filename: string,
-  cwd = process.cwd()
+  cwd = process.cwd(),
 ): Promise<string | undefined> {
   const pkgDir = await findPkgDir(cwd);
   if (!pkgDir) {
@@ -96,19 +86,6 @@ export async function findInPkgDir(
   return path.join(pkgDir, filename);
 }
 
-/**
- * Finds a `typedoc.json`, expected to be a sibling of `package.json`
- *
- * Caches the result.
- * @param cwd - Current working directory
- * @returns Path to `typedoc.json`
- */
-export const findTypeDocJsonPath = _.memoize(async (cwd = process.cwd()) => {
-  const filepath = await findUp(NAME_TYPEDOC_JSON, {cwd, type: 'file'});
-  log.debug('Found `typedoc.json` at %s', filepath);
-  return filepath;
-});
-
 /**
  * Finds an `mkdocs.yml`, expected to be a sibling of `package.json`
  *
@@ -126,20 +103,20 @@ export const findMkDocsYml = _.memoize(_.partial(findInPkgDir, NAME_MKDOCS_YML))
  */
 async function _readPkgJson(
   cwd: string,
-  normalize: true
+  normalize: true,
 ): Promise<{pkgPath: string; pkg: NormalizedPackageJson}>;
 async function _readPkgJson(
   cwd: string,
-  normalize?: false
+  normalize?: false,
 ): Promise<{pkgPath: string; pkg: PackageJson}>;
 async function _readPkgJson(
   cwd: string,
-  normalize?: boolean
+  normalize?: boolean,
 ): Promise<{pkgPath: string; pkg: PackageJson | NormalizedPackageJson}> {
   const pkgDir = await findPkgDir(cwd);
   if (!pkgDir) {
     throw new DocutilsError(
-      `Could not find a ${NAME_PACKAGE_JSON} near ${cwd}; please create it before using this utility`
+      `Could not find a ${NAME_PACKAGE_JSON} near ${cwd}; please create it before using this utility`,
     );
   }
   const pkgPath = path.join(pkgDir, NAME_PACKAGE_JSON);
@@ -158,27 +135,12 @@ async function _readPkgJson(
  */
 export const readPackageJson = _.memoize(_readPkgJson);
 
-/**
- * Reads a `typedoc.json` file and returns its parsed contents.
- *
- * TypeDoc expands the "extends" field, which is why we use its facilities.  It, unfortunately, is a
- * blocking operation.
- */
-export const readTypedocJson = _.memoize((typedocJsonPath: string) => {
-  const app = new Application();
-  app.options.setValue('plugin', 'none');
-  app.options.setValue('logger', 'none');
-  app.options.addReader(new TypeDocReader());
-  app.bootstrap({options: path.dirname(typedocJsonPath)});
-  return app.options.getRawValues();
-});
-
 /**
  * Reads a JSON5 file and parses it
  */
 export const readJson5 = _.memoize(
   async <T extends JsonValue>(filepath: string): Promise<T> =>
-    JSON5.parse(await fs.readFile(filepath, 'utf8'))
+    JSON5.parse(await fs.readFile(filepath, 'utf8')),
 );
 
 /**
@@ -186,7 +148,7 @@ export const readJson5 = _.memoize(
  */
 export const readJson = _.memoize(
   async <T extends JsonValue>(filepath: string): Promise<T> =>
-    JSON.parse(await fs.readFile(filepath, 'utf8'))
+    JSON.parse(await fs.readFile(filepath, 'utf8')),
 );
 
 /**
@@ -225,11 +187,6 @@ const whichPython = _.partial(cachedWhich, NAME_PYTHON, {nothrow: true});
  */
 const whichPython3 = _.partial(cachedWhich, `${NAME_PYTHON}3`, {nothrow: true});
 
-/**
- * Finds `typedoc` executable
- */
-const whichTypeDoc = _.partial(cachedWhich, NAME_TYPEDOC, {nothrow: true});
-
 /**
  * `mike` cannot be invoked via `python -m`, so we need to find the script.
  */
@@ -254,21 +211,7 @@ export const findMike = _.partial(async () => {
         return mikePath;
       }
     }
-  }
-  catch {}
-});
-
-/**
- * Finds the `typedoc` executable.
- *
- * Looks in the `node_modules/.bin` dir from the current working directory, and if this fails, in the `node_modules` dir for the file which `.bin/typedoc` should be a symlink of, and if _that_ fails, try the `PATH`.
- */
-export const findTypeDoc = _.memoize(async (cwd = process.cwd()): Promise<string | undefined> => {
-  // .cmd is for win32, of course. note that glob _always_ uses posix dir separators.
-  const globResult =
-    (await fs.glob('node_modules/.bin/typedoc?(.cmd)', {cwd, nodir: true})) ??
-    (await fs.glob('node_modules/**/typedoc/bin/typedoc', {cwd, nodir: true, follow: true}));
-  return _.first(globResult) ?? (await whichTypeDoc());
+  } catch {}
 });
 
 /**
@@ -277,7 +220,7 @@ export const findTypeDoc = _.memoize(async (cwd = process.cwd()): Promise<string
  * `python3` is preferred over `python`, since the latter could be Python 2.
  */
 export const findPython = _.memoize(
-  async (): Promise<string | undefined> => (await whichPython3()) ?? (await whichPython())
+  async (): Promise<string | undefined> => (await whichPython3()) ?? (await whichPython()),
 );
 
 /**
@@ -313,16 +256,5 @@ export const readMkDocsYml = _.memoize(
       }
     }
     return mkDocsYml;
-  }
+  },
 );
-
-/**
- * Given an abs path to a directory, return a list of all abs paths of all directories in it
- */
-export const findDirsIn = _.memoize(async (dirpath: string): Promise<string[]> => {
-  if (!path.isAbsolute(dirpath)) {
-    throw new DocutilsError(`Expected absolute path, got '${dirpath}'`);
-  }
-  const dirEnts = await fs.readdir(dirpath, {withFileTypes: true});
-  return dirEnts.filter((ent) => ent.isDirectory()).map((ent) => path.join(dirpath, ent.name));
-});

package/lib/index.ts

@@ -3,7 +3,6 @@
  * @module
  */
 
-export * from './mike';
 export * from './builder';
 export * from './validate';
 export * from './scaffold';