Add documentation

docs/developer/plugin-list.asciidoc

@@ -540,6 +540,11 @@ Elastic.
 |Add tagging capability to saved objects
 
 
+|{kib-repo}blob/{branch}/x-pack/plugins/screenshotting/README.md[screenshotting]
+|This plugin provides functionality to take screenshots of the Kibana pages.
+It uses Chromium and Puppeteer underneath to run the browser in headless mode.
+
+
 |{kib-repo}blob/{branch}/x-pack/plugins/searchprofiler/README.md[searchprofiler]
 |The search profiler consumes the Profile API
 by sending a search API with profile: true enabled in the request body. The response contains

x-pack/plugins/screenshotting/README.md

@@ -1,34 +1,11 @@
-# Kibana Reporting
+# Kibana Screenshotting
 
-An awesome Kibana reporting plugin
+This plugin provides functionality to take screenshots of the Kibana pages.
+It uses Chromium and Puppeteer underneath to run the browser in headless mode.
 
-# Development
+## API
 
-Assuming you've checked out x-plugins next to kibana...
+The plugin exposes most of the functionality in the start contract.
+The Chromium download and setup is happening during the setup stage.
 
-- Run `yarn kbn bootstrap`
-- Run `yarn start` to watch for and sync files on change
-- Open a new terminal to run Kibana - use `yarn start` to launch it in dev mode
-  - Kibana will automatically restart as files are synced
-  - If you need debugging output, run `DEBUG=reporting yarn start` instead
-
-If you have installed this somewhere other than via x-plugins, and next to the kibana repo, you'll need to change the `pathToKibana` setting in `gulpfile.js`
-
-# Conventions
-
-This plugins adopts some conventions in addition to or in place of conventions in Kibana (at the time of the plugin's creation):
-
-## Folder structure
-```
-export_types/ (contains public and server aspects of the different export types) 
-  printable_pdf/ 
-    public/
-    server/
-  csv/
-    public/
-    server/
-public/ (shared public code for all export types)
-server/ (shared server code for all export types)
-```
-
-This folder structure treats the different export_types like Plugins, with their public/server code being separate in a folder.
+To learn more about the public API, please use automatically generated API reference or generated TypeDoc comments.

x-pack/plugins/screenshotting/common/context.ts

@@ -5,6 +5,10 @@
  * 2.0.
  */
 
+/**
+ * Screenshot context.
+ * This is a serializable object that can be passed from the screenshotting backend and then deserialized on the target page.
+ */
 export type Context = Record<string, unknown>;
 
 /**

x-pack/plugins/screenshotting/common/layout.ts

@@ -12,7 +12,14 @@ import type { Ensure, SerializableRecord } from '@kbn/utility-types';
  */
 export type Size = Ensure<
   {
+    /**
+     * Layout width.
+     */
     width: number;
+
+    /**
+     * Layout height.
+     */
     height: number;
   },
   SerializableRecord
@@ -30,11 +37,29 @@ export interface LayoutSelectorDictionary {
   timefilterDurationAttribute: string;
 }
 
+/**
+ * Screenshot layout parameters.
+ */
 export type LayoutParams = Ensure<
   {
+    /**
+     * Unique layout name.
+     */
     id?: string;
+
+    /**
+     * Layout sizing.
+     */
     dimensions?: Size;
+
+    /**
+     * Element selectors determining the page state.
+     */
     selectors?: Partial<LayoutSelectorDictionary>;
+
+    /**
+     * Page zoom.
+     */
     zoom?: number;
   },
   SerializableRecord

x-pack/plugins/screenshotting/public/index.ts

@@ -7,6 +7,9 @@
 
 import { ScreenshottingPlugin } from './plugin';
 
+/**
+ * Screenshotting plugin entry point.
+ */
 export function plugin(...args: ConstructorParameters<typeof ScreenshottingPlugin>) {
   return new ScreenshottingPlugin(...args);
 }

x-pack/plugins/screenshotting/public/plugin.tsx

@@ -8,10 +8,19 @@
 import type { Plugin } from 'src/core/public';
 import { ContextStorage } from './context_storage';
 
+/**
+ * Setup public contract.
+ */
 export interface ScreenshottingSetup {
+  /**
+   * Gathers screenshot context that has been set on the backend.
+   */
   getContext: ContextStorage['get'];
 }
 
+/**
+ * Start public contract.
+ */
 export type ScreenshottingStart = ScreenshottingSetup;
 
 export class ScreenshottingPlugin implements Plugin<ScreenshottingSetup, ScreenshottingStart> {

x-pack/plugins/screenshotting/server/browsers/chromium/driver.ts

@@ -99,6 +99,9 @@ function getDisallowedOutgoingUrlError(interceptedUrl: string) {
   );
 }
 
+/**
+ * @internal
+ */
 export class HeadlessChromiumDriver {
   private listenersAttached = false;
   private interceptedCount = 0;

x-pack/plugins/screenshotting/server/browsers/chromium/driver_factory/metrics.ts

@@ -29,10 +29,28 @@ interface NormalizedMetrics extends Required<PuppeteerMetrics> {
   ProcessTime: number;
 }
 
+/**
+ * Collected performance metrics during a screenshotting session.
+ */
 export interface PerformanceMetrics {
+  /**
+   * The percentage of CPU time spent by the browser divided by number or cores.
+   */
   cpu: number;
+
+  /**
+   * The percentage of CPU in percent untis.
+   */
   cpuInPercentage: number;
+
+  /**
+   * The total amount of memory used by the browser.
+   */
   memory: number;
+
+  /**
+   * The total amount of memory used by the browser in megabytes.
+   */
   memoryInMegabytes: number;
 }
 

x-pack/plugins/screenshotting/server/config/index.ts

@@ -8,6 +8,9 @@
 import type { PluginConfigDescriptor } from 'src/core/server';
 import { ConfigSchema, ConfigType } from './schema';
 
+/**
+ * Screenshotting plugin configuration schema.
+ */
 export const config: PluginConfigDescriptor<ConfigType> = {
   schema: ConfigSchema,
   deprecations: ({ renameFromRoot }) => [

x-pack/plugins/screenshotting/server/index.ts

@@ -7,6 +7,9 @@
 
 import { ScreenshottingPlugin } from './plugin';
 
+/**
+ * Screenshotting plugin entry point.
+ */
 export function plugin(...args: ConstructorParameters<typeof ScreenshottingPlugin>) {
   return new ScreenshottingPlugin(...args);
 }

x-pack/plugins/screenshotting/server/layouts/index.ts

@@ -11,14 +11,24 @@ import type { HeadlessChromiumDriver } from '../browsers';
 import type { BaseLayout } from './base_layout';
 
 interface LayoutSelectors {
-  // Fields that are not part of Layout: the instances
-  // independently implement these fields on their own
+  /**
+   * Element selectors determining the page state.
+   */
   selectors: LayoutSelectorDictionary;
+
+  /**
+   * A callback to position elements before taking a screenshot.
+   * @param browser Browser adapter instance.
+   * @param logger Message logger.
+   */
   positionElements?(browser: HeadlessChromiumDriver, logger: Logger): Promise<void>;
 }
 
 export type Layout = BaseLayout & LayoutSelectors & Partial<Size>;
 
+/**
+ * Supported layout types.
+ */
 export const LayoutTypes = {
   PRESERVE_LAYOUT: 'preserve_layout',
   PRINT: 'print',

x-pack/plugins/screenshotting/server/plugin.ts

@@ -23,8 +23,21 @@ interface SetupDeps {
   screenshotMode: ScreenshotModePluginSetup;
 }
 
+/**
+ * Start public contract.
+ */
 export interface ScreenshottingStart {
+  /**
+   * Runs browser diagnostics.
+   * @returns Observable with output messages.
+   */
   diagnose: HeadlessChromiumDriverFactory['diagnose'];
+
+  /**
+   * Takes screenshots of multiple pages.
+   * @param options Screenshots session options.
+   * @returns Observable with screenshotting results.
+   */
   getScreenshots(options: ScreenshotOptions): ReturnType<typeof getScreenshots>;
 }
 

x-pack/plugins/screenshotting/server/screenshots/get_screenshots.ts

@@ -12,8 +12,19 @@ import type { HeadlessChromiumDriver } from '../browsers';
 import type { ElementsPositionAndAttribute } from './get_element_position_data';
 
 export interface Screenshot {
+  /**
+   * Screenshot PNG image data.
+   */
   data: Buffer;
+
+  /**
+   * Screenshot title.
+   */
   title: string | null;
+
+  /**
+   * Screenshot description.
+   */
   description: string | null;
 }
 

x-pack/plugins/screenshotting/server/screenshots/index.ts

@@ -30,8 +30,19 @@ export interface ScreenshotOptions extends ScreenshotObservableOptions {
 }
 
 export interface ScreenshotResult {
+  /**
+   * Used layout instance constructed from the given options.
+   */
   layout: Layout;
+
+  /**
+   * Collected performance metrics during the screenshotting session.
+   */
   metrics$: Observable<PerformanceMetrics>;
+
+  /**
+   * Screenshotting results.
+   */
   results: ScreenshotObservableResult[];
 }
 

x-pack/plugins/screenshotting/server/screenshots/observable.ts

@@ -27,22 +27,65 @@ import { waitForRenderComplete } from './wait_for_render';
 import { waitForVisualizations } from './wait_for_visualizations';
 
 export interface PhaseTimeouts {
+  /**
+   * Open URL phase timeout.
+   */
   openUrl: number;
+
+  /**
+   * Timeout of the page readiness phase.
+   */
   waitForElements: number;
+
+  /**
+   * Timeout of the page render phase.
+   */
   renderComplete: number;
+
+  /**
+   * An additional delay to wait until the visualizations are ready.
+   */
   loadDelay: number;
 }
 
 export interface ScreenshotObservableOptions {
+  /**
+   * The browser timezone that will be emulated in the browser instance.
+   * This option should be used to keep timezone on server and client in sync.
+   */
   browserTimezone?: string;
+
+  /**
+   * Custom headers to be sent with each request.
+   */
   conditionalHeaders: ConditionalHeaders;
+
+  /**
+   * Timeouts for each phase of the screenshot.
+   */
   timeouts: PhaseTimeouts;
+
+  /**
+   * The list or URL to take screenshots of.
+   * Every item can either be a string or a tuple containing a URL and a context.
+   */
   urls: UrlOrUrlWithContext[];
 }
 
 export interface ScreenshotObservableResult {
+  /**
+   * Used time range filter.
+   */
   timeRange: string | null;
+
+  /**
+   * Taken screenshots.
+   */
   screenshots: Screenshot[];
+
+  /**
+   * Error that occurred during the screenshotting.
+   */
   error?: Error;
 
   /**
@@ -51,6 +94,10 @@ export interface ScreenshotObservableResult {
    * does no further sanitization on these strings.
    */
   renderErrors?: string[];
+
+  /**
+   * @internal
+   */
   elementsPositionAndAttributes?: ElementsPositionAndAttribute[]; // NOTE: for testing
 }