mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 09:48:58 -04:00
1b85815402
Fixes https://github.com/elastic/kibana/issues/149344 This PR migrates all plugins to packages automatically. It does this using `node scripts/lint_packages` to automatically migrate `kibana.json` files to `kibana.jsonc` files. By doing this automatically we can simplify many build and testing procedures to only support packages, and not both "packages" and "synthetic packages" (basically pointers to plugins). The majority of changes are in operations related code, so we'll be having operations review this before marking it ready for review. The vast majority of the code owners are simply pinged because we deleted all `kibana.json` files and replaced them with `kibana.jsonc` files, so we plan on leaving the PR ready-for-review for about 24 hours before merging (after feature freeze), assuming we don't have any blockers (especially from @elastic/kibana-core since there are a few core specific changes, though the majority were handled in #149370). --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
81 lines
4 KiB
Text
81 lines
4 KiB
Text
---
|
|
id: kibDevDocsApiWelcome
|
|
slug: /kibana-dev-docs/api-meta/welcome
|
|
title: Welcome
|
|
description: How to use our automatically generated API documentation
|
|
date: 2021-02-25
|
|
tags: ['kibana','dev', 'contributor', 'api docs']
|
|
---
|
|
|
|
Welcome to our automatically generated typescript API
|
|
documentation for every plugin that exposes a <DocLink id="kibPlatformIntro" section="public-plugin-api" text="public API"/>!
|
|
|
|
<DocCallOut color="warning" title="Experimental">
|
|
This documentation is being automatically generated using an
|
|
[_experimental_ system](https://github.com/elastic/kibana/blob/main/legacy_rfcs/text/0014_api_documentation.md). That means
|
|
it may be removed or modified at any time. If you have any questions, feedback or concerns, please create an issue using
|
|
the label `APIDocs`, or reach out to the Kibana Tech Leads
|
|
who are temporarily owning and maintaining this system.
|
|
</DocCallOut>
|
|
|
|
## What is included
|
|
|
|
Every plugin that
|
|
<DocLink id="kibPlatformIntro" section="public-plugin-api" text="exposes functionality for other plugins to use"/> will have
|
|
API documentation automatically generated (note this system
|
|
does *not* handle REST APIs).
|
|
|
|
<DocCallOut title="@internal tags">API items that have an `@internal` in the comment are not
|
|
included in the documentation system.</DocCallOut>
|
|
|
|
## How it works
|
|
|
|
If you change or delete a public plugin API, or add a new one, you will have to run the command `node scripts/build_api_docs` in order to update the
|
|
docs in your PR, or CI will fail. When this happens, consider:
|
|
|
|
1. If this affects an existing API item, have you emailed the `kibana-contributors` list with a heads up? It's important to give advance
|
|
notice, since there may be corner cases you aren't aware of, even if your PR passes CI.
|
|
2. If the change you are making aren't relevant to contributors, consider a) making the API private, or b) adding the `@internal` flag to it.
|
|
|
|
## Q & A
|
|
|
|
### Why do I not see my plugin's public API?
|
|
|
|
There is one extra step required to have your API docs show up in the _navigation_ of the docs system. Follow
|
|
the instructions <DocLink id="docsSetup" section="configure-the-nav-for-your-content" text="here" /> to learn how to
|
|
configure the navigation menu. The nav file you need to
|
|
edit is: [https://github.com/elastic/elastic-docs/blob/main/config/nav-kibana-dev.ts](https://github.com/elastic/elastic-docs/blob/main/config/nav-kibana-dev.ts)
|
|
|
|
Your API docs will exist in the top level [`api_docs` folder](https://github.com/elastic/kibana/tree/main/api_docs) and will use a doc id of the pattern `kib${PluginName}PluginApi`.
|
|
|
|
### Why is a referenced API item not showing up as clickable?
|
|
|
|
There are a few reasons his could happen. First, check if you are exporting the API item. For example,
|
|
if you have the following in your `my_plugin/public/index.ts` file:
|
|
|
|
```
|
|
type Bar = { id: string };
|
|
export type Foo = Bar | string;
|
|
```
|
|
|
|
`Bar`, in the signature of `Foo`, will not be clickable because it would result in a broken link. `Bar` is not publicly exported!
|
|
|
|
If that isn't the case, please file an issue, it could be a bug with the system.
|
|
|
|
### Why are the docs so slow?
|
|
|
|
We are [aware of some performance issues](https://github.com/elastic/elastic-docs/issues/274) with deeply nested, or large APIs.
|
|
|
|
In the short term, the best thing you can do is avoid deeply nested API items. Use interfaces rather than inlined objects. Also consider
|
|
adding `serviceFolders` in your kibana.jsonc. This will automatically split your docs up based on which APIs are defined within the service folders.
|
|
They will get built into a doc with an id of
|
|
`kib${PluginName}${ServiceName}PluginApi`. The data plugin does this, so you
|
|
can [check that out as an example](https://github.com/elastic/kibana/blob/main/src/plugins/data/kibana.json#L13).
|
|
|
|
If that isn't the case and you are still experiencing performance issues, please file an issue!
|
|
|
|
### Where do I ask questions or give feedback?
|
|
|
|
If you have any questions or issues, please reach out to the Kibana Tech Leads or create an issue [here](https://github.com/elastic/kibana/issues)
|
|
and use the label `APIDocs`.
|
|
|