@appium/typedoc-plugin-appium

@appium/typedoc-plugin-appium

TypeDoc plugin for Appium & its extensions

Overview

This package leverages TypeDoc to generate command documentation (HTTP endpoints, payload information, etc.) for Appium v2+ drivers and plugins.

Important Note

If you are an Appium extension author and just want to build HTML docs, don't install this directly--instead, install @appium/docutils, which is a higher-level package that configures everything for you.

If you only want to build markdown docs for your extension, then you can use this package directly.

Installation

npm v8+ is required to install this package.

npm install @appium/typedoc-plugin-appium --save-dev

The above command installs the plugin as well as all necessary peer dependencies. See package.json for the full list of dependencies.

Usage

TypeDoc is configured via a typedoc.json or typedoc.js file (read the docs for more information).

An Appium extension author wishing to generate markdown documentation for their extension will need to create a typedoc.json. At minimum, it should contain:

{
  "entryPointStrategy": "packages",
  "entryPoints": ["."],
  "name": "<name of extension>",
  "theme": "appium",
  "out": "<path to output directory>"
}

Once this file is created, you can run typedoc to generate the documentation, and it will be output into the out directory as configured above.

Options

This plugin supports all of the options from typedoc-plugin-markdown, as well as the following:

outputModules

boolean - Output module, class, interface, and other type information (the usual TypeDoc output) in addition to command documentation. This is needed for full documentation of types. Default value: true

outputBuiltinCommands

boolean - Outputs all commands and types from Appium builtins--not just your extension. This is intended to be used by Appium itself. Default value: false

packageTitles

Array<{name: string, title: string}>: An array of objects containing module name name and display name title. By default, the module name is used for the title; use this to override that behavior. Default value: undefined

commandsDir

string - The name of the "commands" directory relative to the TypeDoc output directory (out). Default value: commands

forceBreadcrumbs

boolean - Forces breadcrumbs to be output; overrides hideBreadcrumbs from typedoc-plugin-markdown. Default value: false

Development

This packages uses snapshot tests to assert the generated markdown is correct. If you have made changes which affect the plugin's output, you will need to update the snapshots.

To update the snapshots, execute:

UPDATE_SNAPSHOT=1 npm run test:e2e

This will (likely) modify the snapshots in your working copy, so you will then need to commit them.

License

Copyright © 2022 OpenJS Foundation. Licensed Apache-2.0