Documentation

Docs should be written during development and accompany PRs when relevant. There are multiple types of documentation, and different places to add each.

User-facing features are documented in Markdown under docs/ and published to elastic.co/docs via the Elastic Docs v3 system. Authoring and syntax guidance lives in the contributor docs, and the tooling itself is documented at elastic.github.io/docs-builder.

To preview docs locally, install docs-builder and run it from the Kibana repo root.

Install:

curl -sL https://ela.st/docs-builder-install | sh
		

Run a one-off build to surface warnings and errors:

docs-builder
		

Start a live-preview server at http://localhost:3000:

docs-builder serve
		

REST APIs are documented via OpenAPI Spec (OAS) generated directly from the route registration code. Define your route schemas with @kbn/config-schema or @kbn/zod, and the generated OAS will flow through scripts/capture_oas_snapshot.js into the published bundles at elastic.co/docs/api/doc/kibana (ESS) and elastic.co/docs/api/doc/serverless (Serverless).

Start here:

• Generating OAS for HTTP APIs — how to register routes, attach schemas and examples, capture the OAS snapshot, and get your path included in the published bundle.
• Guidelines for HTTP API design in Kibana — schema patterns that produce clean OAS, plus documentation, security, and versioning requirements for public APIs.

Developer documentation can be segmented into two types: internal plugin details, and information on extending Kibana. This guide is meant to serve the latter.

Internal plugin details can be kept alongside the code it describes. Information about extending Kibana may go in the root of your plugin or package folder.

The high-level developer documentation located in the docs/extend folder attempts to follow divio documentation guidance. Getting started and Key concepts sections are explanation oriented, while Tutorials falls under both tutorials and how to. The API documentation section is reference material.

Developers may choose to keep information that is specific to a particular plugin or package alongside the code.

A fresh pair of eyes are invaluable. Recruit new hires to read, review and update documentation. Leads should also periodically review documentation to ensure it stays up to date. File issues any time you notice documentation is outdated.

Documentation in the Kibana Developer Guide is targeted towards developers building Kibana plugins. Keep implementation details about internal plugin code out of these docs.

When a developer first lands in our docs, think about their journey. Introduce basic concepts before diving into details. The left navigation should be set up so documents on top are higher level than documents near the bottom.

It's easy to forget what it felt like to first write code in Kibana, but do your best to frame these docs "outside-in". Don't use esoteric, internal language unless a definition is documented and linked. The fresh eyes of a new hire can be a great asset.

Every function, class, interface, type, parameter and property that is exposed to other plugins should have a TSDoc-style comment.

• Use @param tags for every function parameter.
• Use @returns tags for return types.
• Use @throws when appropriate.
• Use @beta or @deprecated when appropriate.
• Use @removeBy {version} on @deprecated APIs. The version should be the last version the API will work in. For example, @removeBy 7.15 means the API will be removed in 7.16. This lets us avoid mid-release cycle coordination. The API can be removed as soon as the 7.15 branch is cut.
• Use @internal to indicate this API item is intended for internal use only, which will also remove it from the docs.

Prefer types and interfaces over complex inline objects. For example, prefer:

/**
* The SearchSpec interface contains settings for creating a new SearchService, like
* username and password.
*/
export interface SearchSpec {
 /**
  * Stores the username. Duh,
  */
 username: string;
 /**
  * Stores the password. I hope it's encrypted!
  */
 password: string;
}

 /**
  * Retrieve search services
  * @param searchSpec Configuration information for initializing the search service.
  * @returns the id of the search service
  */
export getSearchService: (searchSpec: SearchSpec) => string;
		

over:

/**
  * Retrieve search services
  * @param searchSpec Configuration information for initializing the search service.
  * @returns the id of the search service
  */
export getSearchService: (searchSpec: { username: string; password: string }) => string;
		

In the former, there will be a link to the SearchSpec interface with documentation for the username and password properties. In the latter the object will render inline, without comments:

When a publicly exported API item references a private type, this results in a broken link in our docs system. The private type is, by proxy, part of your public API, and as such, should be exported.

Do:

export interface AnInterface { bar: string };
export type foo: string | AnInterface;
		

Don't:

interface AnInterface { bar: string };
export type foo: string | AnInterface;
		

Pick not only ends up being unhelpful in our documentation system, but it's also of limited help in your IDE. For that reason, avoid Pick and other similarly complex types on your public API items. Using these semantics internally is fine.

There are three great ways to debug issues with the API infrastructure.

1. Write a test

api_doc_suite.test.ts is a pretty comprehensive test suite that builds the test docs inside the fixtures folder.

Edit the code inside __fixtures__ to replicate the bug, write a test to track what should happen, then run yarn jest api_doc_suite.

Once you've verified the bug is reproducible, use debug messages to narrow down the problem. This is much faster than running the entire suite to debug.

2. Use ts-ast-viewer.com

This nifty website will let you add some types and see how the system parses it. For example, the link above shows there is a QuestionToken as a sibling to the FunctionType which is why this bug reported children being lost. The API infra system didn't categorize the node as a function type node.

3. Play around with ts-morph in a Code Sandbox.

You can fork this Code Sandbox example that was used to explore how to generate the node signature in different ways (e.g. node.getType.getText() shows different results than node.getType.getText(node)). Here is another messy example.

The code sandbox approach can be a lot faster to iterate compared to running it in Kibana.

Running Kibana with yarn start --run-examples will include all example plugins. These are tested examples of platform services in use. We strongly encourage anyone providing a platform level service or building block to include a tutorial that links to a tested example plugin. This is better than relying on copied code snippets, which can quickly get out of date.

You can also visit these examples plugins hosted online. Note that because anonymous access is enabled, some of the demos are currently not working.