Document new platform service APIs

[rudolf]

[WIP]

Get the documentation for the new platform service API's on the elastic documentation website.

Goals:

• Reuse Elastic's existing documentation infrastructure (based on asciidoc)
• Lower the barrier to writing good documentation, generate docs as far as possible
• Should be robust and maintenance free (we want to write docs, not spend time on documentation infrastructure)

Proposal

Use api-extractor and api-documenter to generate documentation from tsdoc comments.

1. api-extractor
   • Detect a project’s exported API surface
   • Capture the contracts in a concise report designed to facilitate review
   • Warn about common mistakes (e.g. missing exports, inconsistent visibility, etc.)
   • Generate *.d.ts rollups with trimming according to release type
   • Output API documentation in a portable format that’s easy to integrate with your content pipeline
2. api-documenter
   • Reads *.api.json files created by api-extractor to generate markdown / yml files
   • Has a flexible architecture for supporting custom formats, we could probably easily create an asciidoc emitter based on the markdown emitter

Exactly how we get the docs out of api-documenter into asciidoc still needs to be explored, here are a few options:

1. api-extractor –> *.api.json file –> api-documenter –> *.md files –> html –> embed in asciidoc
2. api-extractor –> *.api.json file –> api-documenter –> *.md files –> kramdown-asciidoc –> asciidoc
3. api-extractor –> *.api.json file –> api-documenter –> new asciidoc generator -> asciidoc

Example markdown and preview using api-extractor and api-documenter. Showing the logger interface since it currently has the most useful documentation.

[elasticmachine]

Pinging @elastic/kibana-platform