[discuss] Future of API docs in Kibana

[lizozom]

This issue expands on #41833, specifically on the topic of auto generated API documentation for Kibana.

API documentation refers to the documentation generated by running APIExtractor, which is being used to both track API changes (for stability purposes) and for developers who require it.

Accessibility

• Generated documentation should be linked from plugin main md files
• Generated documentation should be uploaded to elastic.co website under the Kibana: Explore, Visualize, and Share book at https://www.elastic.co/guide/en/kibana/api/current/index.html.
• Create a single entry point for navigating docs for core and all other plugins.

Focus areas

• Plugin setup \ start contracts should be always documented
• Core
• Data
• Embeddables
• Expressions
• Kibana utils
• Kibana React

API cleanup and minimization

• APIs consumed by functional tests only, should not be exported. Instead tests should import it from an internal path, suppressing the TSLint error
• Make sure that exported values have a clear prefix

Additional functionality

• Add more plugins to generate docs
• Generate docs for a single plugin

[elasticmachine]

Pinging @elastic/kibana-app-arch (Team:AppArch)

[KOTungseth]

To bring consistency across all Elastic API docs, some of the doc guild created API reference and definition templates. When the Kibana API docs are automatically generated, would we be able to use these same structures? Or is the plan to improve on structure as well?

[stacey-gammon]

I think this issue may be moot now that we have the new API docs system. Please feel free to re-open if you think it is still relevant.