@appium/typedoc-plugin-appium
Version:
TypeDoc plugin for Appium & its extensions
126 lines • 6.08 kB
JavaScript
;
/**
* Contains the {@link load entry point} for `@appium/typedoc-plugin-appium`
* @module
*/
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __exportStar = (this && this.__exportStar) || function(m, exports) {
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
};
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.postProcess = exports.convert = exports.setup = exports.load = void 0;
const lodash_1 = __importDefault(require("lodash"));
const pluralize_1 = __importDefault(require("pluralize"));
const typedoc_1 = require("typedoc");
const converter_1 = require("./converter");
const logger_1 = require("./logger");
const model_1 = require("./model");
const options_1 = require("./options");
const theme_1 = require("./theme");
let log;
/**
* Loads the Appium TypeDoc plugin.
*
* @param app - TypeDoc Application
* @returns Unused by TypeDoc, but can be consumed programmatically.
*/
function load(app) {
// register our custom theme. the user still has to choose it
(0, exports.setup)(app);
// TypeDoc does not expect a return value here, but it's useful for testing.
// note that this runs both methods "in parallel", but the `convert` method will always resolve
// first, and `postProcess` won't do any real work until that happens.
return Promise.allSettled([convert(app), postProcess(app)]);
}
exports.load = load;
/**
* Registers theme and options, then monkeys with the options
*/
exports.setup = lodash_1.default.flow(theme_1.configureTheme, options_1.configureOptions);
/**
* Finds commands and creates new reflections for them, adding them to the project.
*
* Resolves after {@linkcode Converter.EVENT_RESOLVE_END} emits and when it's finished.
* @param app Typedoc Application
* @returns A {@linkcode ConvertResult} receipt from the conversion
*/
async function convert(app) {
return new Promise((resolve) => {
app.converter.once(typedoc_1.Converter.EVENT_RESOLVE_END,
/**
* This listener _must_ trigger on {@linkcode Converter.EVENT_RESOLVE_END}, because TypeDoc's
* internal plugins do some post-processing on the project's reflections--specifically, it
* finds `@param` tags in a `SignatureReflection`'s `comment` and "moves" them into the
* appropriate `ParameterReflections`. Without this in place, we won't be able aggregate
* parameter comments and they will not display in the generated docs.
*/
(ctx) => {
let extensionReflections;
let projectCommands;
// we don't want to do this work if we're not using the custom theme!
log = log ?? new logger_1.AppiumPluginLogger(app.logger, model_1.NS);
// this should not be necessary given the `AppiumPluginOptionsReader` forces the issue, but
// it's a safeguard nonetheless.
if (app.renderer.themeName === theme_1.THEME_NAME) {
// this queries the declarations created by TypeDoc and extracts command information
projectCommands = (0, converter_1.convertCommands)(ctx, log);
if (!projectCommands) {
log.verbose('Skipping creation of reflections');
resolve({ ctx });
return;
}
// this creates new custom reflections from the data we gathered and registers them
// with TypeDoc
extensionReflections = (0, converter_1.createReflections)(ctx, log, projectCommands);
}
else {
log.warn(`Appium theme disabled! Use "theme: 'appium'" in your typedoc.json`);
}
resolve({ ctx, extensionReflections, projectCommands });
});
});
}
exports.convert = convert;
/**
* Optionally omits the default TypeDoc reflections from the project based on the `outputModules` option.
*
* Resolves after {@linkcode Converter.EVENT_RESOLVE_END} emits and when it's finished.
* @param app Typedoc application
* @returns Typedoc `Context` at the time of the {@linkcode Converter.EVENT_RESOLVE_END} event
*/
async function postProcess(app) {
log = log ?? new logger_1.AppiumPluginLogger(app.logger, model_1.NS);
return new Promise((resolve) => {
app.converter.once(typedoc_1.Converter.EVENT_RESOLVE_END, (ctx) => {
let removed;
// if the `outputModules` option is false, then we want to remove all the usual TypeDoc reflections.
if (!app.options.getValue(options_1.declarations.outputModules.name)) {
removed = (0, converter_1.omitDefaultReflections)(ctx.project);
log.info('%s omitted from output', (0, pluralize_1.default)('default reflection', removed.size, true));
}
if (!app.options.getValue(options_1.declarations.outputBuiltinCommands.name)) {
const removedBuiltinRefls = (0, converter_1.omitBuiltinReflections)(ctx.project);
removed = new Set([...(removed ?? []), ...removedBuiltinRefls]);
log.info('%s omitted from output', (0, pluralize_1.default)('builtin reflection', removedBuiltinRefls.size, true));
}
resolve({ ctx, removed });
});
});
}
exports.postProcess = postProcess;
__exportStar(require("./options"), exports);
__exportStar(require("./theme"), exports);
//# sourceMappingURL=index.js.map