@appium/docutils 0.2.2 → 0.3.0

package/lib/constants.ts

@@ -86,6 +86,11 @@ export const NAME_ERR_ENOENT = 'ENOENT';
  */
 export const NAME_ERR_EEXIST = 'EEXIST';
 
+/**
+ * Name of the default theme
+ */
+export const NAME_THEME = 'material';
+
 /**
  * Default log level
  */

package/lib/error.ts

@@ -1 +1,7 @@
+/**
+ * A custom error class. This exists so we can use `instanceof` to differentiate between "expected"
+ * exceptions and unexpected ones.
+ * @module
+ */
+
 export class DocutilsError extends Error {}

package/lib/fs.ts

@@ -127,7 +127,10 @@ async function _readPkgJson(
   cwd: string,
   normalize: true
 ): Promise<{pkgPath: string; pkg: NormalizedPackageJson}>;
-async function _readPkgJson(cwd: string): Promise<{pkgPath: string; pkg: PackageJson}>;
+async function _readPkgJson(
+  cwd: string,
+  normalize?: false
+): Promise<{pkgPath: string; pkg: PackageJson}>;
 async function _readPkgJson(
   cwd: string,
   normalize?: boolean
@@ -236,14 +239,14 @@ export const whichMike = _.partial(cachedWhich, NAME_MIKE);
  */
 export const readMkDocsYml = _.memoize(
   async (filepath: string, cwd = process.cwd()): Promise<MkDocsYml> => {
-    let mkDocsYml = <MkDocsYml>await readYaml(filepath);
+    let mkDocsYml = (await readYaml(filepath)) as MkDocsYml;
     if (mkDocsYml.site_dir) {
       mkDocsYml.site_dir = path.resolve(cwd, path.dirname(filepath), mkDocsYml.site_dir);
     }
     if (mkDocsYml.INHERIT) {
       let inheritPath: string | undefined = path.resolve(path.dirname(filepath), mkDocsYml.INHERIT);
       while (inheritPath) {
-        const inheritYml = <MkDocsYml>await readYaml(inheritPath);
+        const inheritYml = (await readYaml(inheritPath)) as MkDocsYml;
         if (inheritYml.site_dir) {
           inheritYml.site_dir = path.resolve(path.dirname(inheritPath), inheritYml.site_dir);
           log.debug('Resolved site_dir to %s', inheritYml.site_dir);

package/lib/index.ts

@@ -1,3 +1,8 @@
+/**
+ * Main entry point
+ * @module
+ */
+
 export * from './mike';
 export * from './builder';
 export * from './validate';

package/lib/init.ts

@@ -126,7 +126,9 @@ export const initMkDocs = createScaffoldTask<InitMkDocsOptions, MkDocsYml>(
       if (repoUrl && !repoName) {
         let {pathname} = new URL(repoUrl);
         pathname = pathname.slice(1);
-        let [owner, repo] = pathname.split('/');
+        const pathparts = pathname.split('/');
+        const owner = pathparts[0];
+        let repo = pathparts[1];
         repo = repo.replace(/\.git$/, '');
         repoName = [owner, repo].join('/');
         if (repoName) {
@@ -158,8 +160,12 @@ export const initMkDocs = createScaffoldTask<InitMkDocsOptions, MkDocsYml>(
 export async function initPython({
   pythonPath = NAME_PYTHON,
   dryRun = false,
+  upgrade = false,
 }: InitPythonOptions = {}): Promise<void> {
   const args = ['-m', 'pip', 'install', '-r', REQUIREMENTS_TXT_PATH];
+  if (upgrade) {
+    args.push('--upgrade');
+  }
   if (dryRun) {
     dryRunLog.info('Would execute command: %s %s', pythonPath, args.join(' '));
   } else {
@@ -214,6 +220,7 @@ export async function init({
   dryRun,
   cwd,
   pythonPath,
+  upgrade,
   typedocJson: typeDocJsonPath,
 }: InitOptions = {}): Promise<void> {
   if (!typescript && typedoc) {
@@ -222,7 +229,7 @@ export async function init({
     );
   }
 
-  if (typescript) {
+  if (typescript && !upgrade) {
     await initTsConfigJson({
       dest: tsconfigJsonPath,
       packageJson: packageJsonPath,
@@ -233,7 +240,7 @@ export async function init({
     });
   }
 
-  if (typedoc) {
+  if (typedoc && !upgrade) {
     await initTypeDocJson({
       dest: typeDocJsonPath,
       packageJson: packageJsonPath,
@@ -244,10 +251,10 @@ export async function init({
   }
 
   if (python) {
-    await initPython({pythonPath, dryRun});
+    await initPython({pythonPath, dryRun, upgrade});
   }
 
-  if (mkdocs) {
+  if (mkdocs && !upgrade) {
     await initMkDocs({
       dest: mkdocsYmlPath,
       cwd,
@@ -262,7 +269,7 @@ export async function init({
   }
 }
 
-export interface InitTypeDocOptions extends ScaffoldTaskOptions {}
+export type InitTypeDocOptions = ScaffoldTaskOptions;
 export interface InitTsConfigOptions extends ScaffoldTaskOptions {
   /**
    * List of source files (globs supported); typically `src` or `lib`
@@ -274,6 +281,11 @@ export interface InitPythonOptions extends ScaffoldTaskOptions {
    * Path to `python` (v3.x) executable
    */
   pythonPath?: string;
+
+  /**
+   * If true, upgrade only
+   */
+  upgrade?: boolean;
 }
 
 /**
@@ -315,5 +327,10 @@ export type InitOptions = Simplify<
      * Path to new or existing `mkdocs.yml` file
      */
     mkdocsYml?: string;
+
+    /**
+     * If `true`, upgrade only
+     */
+    upgrade?: boolean;
   }
 >;

package/lib/mike.js

@@ -1,3 +1,8 @@
+/**
+ * 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';

package/lib/util.ts

@@ -32,6 +32,9 @@ export function stopwatch(id: string) {
 }
 stopwatch.cache = new Map<string, number>();
 
+/**
+ * Converts a tuple to an object; use for extracting parameter types from a function signature
+ */
 export type TupleToObject<
   T extends readonly any[],
   M extends Record<Exclude<keyof T, keyof any[]>, PropertyKey>
@@ -69,7 +72,7 @@ export const argify: (obj: Record<string, string | number | boolean | undefined>
   );
 
 /**
- * Conversion of the parameters of {@linkcode Subprocess.start} to an object.
+ * Conversion of the parameters of {@linkcode SubProcess.start} to an object.
  */
 export type TeenProcessSubprocessStartOpts = Partial<
   TupleToObject<Parameters<SubProcess['start']>, ['startDetector', 'detach', 'timeoutMs']>

package/lib/validate.ts

@@ -1,15 +1,14 @@
 /**
- * Validates an environment for building documentation
+ * Validates an environment for building documentation; used by `validate` command
  *
  * @module
  */
 
-import {fs} from '@appium/support';
+import {fs, util} from '@appium/support';
 import chalk from 'chalk';
 import _ from 'lodash';
 import {EventEmitter} from 'node:events';
 import path from 'node:path';
-import pluralize from 'pluralize';
 import {satisfies} from 'semver';
 import {exec} from 'teen_process';
 import {
@@ -36,7 +35,6 @@ import {
   findMkDocsYml,
   readJson5,
   readTypedocJson,
-  readYaml,
   whichMkDocs,
   whichNpm,
   whichPython,
@@ -287,7 +285,7 @@ export class DocutilsValidator extends EventEmitter {
       return this.requirementsTxt;
     }
 
-    let requiredPackages: PipPackage[] = [];
+    const requiredPackages: PipPackage[] = [];
 
     try {
       let requirementsTxt = await fs.readFile(REQUIREMENTS_TXT_PATH, 'utf8');
@@ -312,6 +310,9 @@ export class DocutilsValidator extends EventEmitter {
     this.emittedErrors.clear();
   }
 
+  /**
+   * Validates that the correct version of `mkdocs` is installed
+   */
   protected async validateMkDocs() {
     let mkDocsPath: string | undefined;
     try {
@@ -466,7 +467,7 @@ export class DocutilsValidator extends EventEmitter {
     const msgParts = [];
     if (missingPackages.length) {
       msgParts.push(
-        `The following required ${pluralize(
+        `The following required ${util.pluralize(
           'package',
           missingPackages.length
         )} could not be found:\n${missingPackages
@@ -476,7 +477,7 @@ export class DocutilsValidator extends EventEmitter {
     }
     if (invalidVersionPackages.length) {
       msgParts.push(
-        `The following required ${pluralize(
+        `The following required ${util.pluralize(
           'package',
           invalidVersionPackages.length
         )} are installed, but at the wrong version:\n${invalidVersionPackages
@@ -533,7 +534,7 @@ export class DocutilsValidator extends EventEmitter {
     }
 
     if (rawTypeDocVersion) {
-      let match = rawTypeDocVersion.match(TYPEDOC_VERSION_REGEX);
+      const match = rawTypeDocVersion.match(TYPEDOC_VERSION_REGEX);
       if (match) {
         typeDocVersion = match[1];
       } else {
@@ -621,7 +622,7 @@ export class DocutilsValidator extends EventEmitter {
       return this.fail(`Could not find TypeScript compiler ("tsc") from ${pkgDir}`);
     }
 
-    let match = rawTypeScriptVersion.match(TYPESCRIPT_VERSION_REGEX);
+    const match = rawTypeScriptVersion.match(TYPESCRIPT_VERSION_REGEX);
     if (match) {
       typeScriptVersion = match[1];
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -46,31 +46,29 @@
     "test:e2e": "echo \"No e2e tests for this package\"",
     "test:smoke": "node ./index.js",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\"",
-    "start": "node ./build/lib/cli.js"
+    "start": "node ./build/lib/cli/index.js"
   },
   "dependencies": {
-    "@appium/support": "^3.1.6",
+    "@appium/support": "^3.1.7",
     "@appium/tsconfig": "^0.2.4",
-    "@appium/typedoc-plugin-appium": "^0.5.0",
+    "@appium/typedoc-plugin-appium": "^0.5.1",
     "@sliphua/lilconfig-ts-loader": "3.2.2",
     "chalk": "4.1.2",
     "consola": "2.15.3",
     "diff": "5.1.0",
     "figures": "3.2.0",
     "find-up": "5.0.0",
-    "glob": "8.1.0",
     "json5": "2.2.3",
-    "lilconfig": "2.0.6",
+    "lilconfig": "2.1.0",
     "lodash": "4.17.21",
     "log-symbols": "4.1.0",
     "pkg-dir": "5.0.0",
-    "pluralize": "8.0.0",
     "read-pkg": "5.2.0",
     "semver": "7.3.8",
     "source-map-support": "0.5.21",
     "teen_process": "2.0.2",
-    "type-fest": "3.6.0",
-    "typedoc": "0.23.25",
+    "type-fest": "3.6.1",
+    "typedoc": "0.23.26",
     "typedoc-plugin-markdown": "3.14.0",
     "typedoc-plugin-resolve-crossmodule-references": "0.3.3",
     "typescript": "4.9.5",
@@ -85,5 +83,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7b4935632222123a4fa7422461f6312f1f0dfbe4"
+  "gitHead": "872b924a97c13142bdb8bf4218a4db324f309ce4"
 }

package/requirements.txt

@@ -1,4 +1,4 @@
 mkdocs==1.4.2
-mkdocs-material==9.0.14
+mkdocs-material==9.1.1
 mkdocs-material-extensions==1.1.1
 mike==1.1.2