Automatically generated Api documentation

[stacey-gammon]

An automated plugin API documentation system using ts-morph.

This effort is going to be broken into three PRs (of which this is the first):

1. The code that creates the API docs. API docs NOT included, nor hooked up to CI. Run yarn build:apidocs to see the generated docs. The folder will be ignored in the first iteration (added to .gitignore).
2. Docs generated and added.
3. Hooked up to CI.

• Precommit hook, detect changes, push back to dev if changes not part of their PR.

This is to make it easier to review.

How to run locally

1. Clone elastic-docs repo locally
2. Edit elastic-docs/config/sources.dev.json and add:

      {
      "type": "file",
      "location": "../kibana/api_docs"
    },
    {
      "type": "file",
      "location": "../kibana/packages/kbn-docs-utils/src/api_docs/tests"
    }

3. Merge https://github.com/elastic/elastic-docs/pull/260, or, add the nav menu items manually by editing elastic-docs/config/nav-kibana-dev.ts:
   Change

    {
      category: 'API documentation',
      items: [{ id: 'kibDevDocsApiWelcome' }],
    },

to

{
      category: 'API documentation',
      items: [
        { id: 'kibDevDocsApiWelcome' },
        { id: 'kibPluginAPluginApi' },
        { id: 'kibPluginAFooPluginApi' },
        { id: 'kibActionsPluginApi' },
        { id: 'kibAdvancedSettingsPluginApi' },
        { id: 'kibAlertsPluginApi' },
        { id: 'kibApmPluginApi' },
        { id: 'kibApmOssPluginApi' },
        { id: 'kibApmPluginApi' },
        { id: 'kibBfetchPluginApi' },
        { id: 'kibCasePluginApi' },
        { id: 'kibCanvasPluginApi' },
        { id: 'kibChartsPluginApi' },
        { id: 'kibCorePluginApi' },
        { id: 'kibCoreChromePluginApi' },
        { id: 'kibCoreHttpPluginApi' },
        { id: 'kibCoreSavedObjectsPluginApi' },
        { id: 'kibDashboardPluginApi' },
        { id: 'kibDashboardEnhancedPluginApi' },
        { id: 'kibDashboardModePluginApi' },
        { id: 'kibDataPluginApi' },
        { id: 'kibDataIndexPatternsPluginApi' },
        { id: 'kibDataAutocompletePluginApi' },
        { id: 'kibDataSearchPluginApi' },
        { id: 'kibDataEnhancedPluginApi' },
        { id: 'kibDataQueryPluginApi' },
        { id: 'kibDataUiPluginApi' },
        { id: 'kibEmbeddablePluginApi' },
        { id: 'kibRuntimeFieldsPluginApi' },
      ],
    },

Note I did not add everything, but enough to get an idea.

• Pull this PR, run yarn build:apidocs
• To build the test files run yarn jest build_api
• Boot up local instance of elastic-docs (yarn start) and navigate to localhost:8000

RFC: #86704

blocked on https://github.com/elastic/elastic-docs/pull/224

Tasks

Features:

• Covert comments with @link tags into links.
• Group by Class, Function, etc. Ensure the rendering uses the order in the array, or pulls start/setup to the top.
• Ingest statistics during API doc generation, like count of missing comments, count of APIs, etc.

Bugs:

• Remove APIs with @internal tag.
• Build the github string with kibana version to pass as source.
• Types that are optional (string | undefined) are being marked as CompoundType, when it should use isRequired: false.
• Interfaces not being exported.
• Failing test about function type.
• Create top level api_docs folder if it doesn't exist, or the script will break.
• Clear api_docs folder every run so plugins that are deleted will have their docs deleted as well.
• Test/fix anchor links.
• Some core types are being lost because common types are not nested inside a common folder.

TODO elastic-docs features:

• anchor links
• description shown by default
• Add known tags and map to a description. beta, alpha, experimental
• Render descriptions with formating like back tics. This won't happen until Katie finishes switching to the Next system.

[kobelb]

There's a bug with getServiceForPath if we have a path like "src/plugins/embed/server/routes/public/foo/index.ts". There's only one usage of getServiceForPath https://github.com/elastic/kibana/pull/86232/files#diff-d3ce0084b5713e36ab23a452ffe50380efc2b94fda541b83b502ab752b25ecabR47 and the scope is known. Perhaps we should just pass the scope to getServiceForPath and use this to create the regex?

[stacey-gammon]

There are two usages, and the one in getPluginApiDocId doesn't have scope available. I added a test and refactored this. The code that has scope available is just part of that function now, and the other usage passes in the plugin directory.

[stacey-gammon]

I think I covered all your comments. Also added support for links in "heritage" clauses of classes and interfaces.

[TinaHeiligers]

LGTM!

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: 49fbd4c
• Storybooks Preview
• Documentation Changes

Metrics [docs]

✅ unchanged

History

• 💔 Build #109191 failed a2b63b7
• 💚 Build #109114 succeeded 279956d
• 💔 Build #109053 failed 3ac3e3d
• 💔 Build #108940 failed 6d1ea2d
• 💚 Build #108653 succeeded eafd497

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

[goodroot]

@stacey-gammon Hi! I realize this is, like, 3 weeks old, but...

Temperate check? How has it been? Any flags so far?

[stacey-gammon]

Hey @goodroot, thanks for asking! It's going well but there are a few issues that I suspect are causing folks to not adopt and use this:

1. Performance. The page may even pop up an error that says "page failed to respond within x seconds". https://github.com/elastic/elastic-docs/issues/274

2. Link scroll positions are off and the section is not auto-expanded. https://github.com/elastic/elastic-docs/issues/262

3. Usage tracking and analytics: https://github.com/elastic/elastic-docs/issues/309. I'll need this to be able to prove whether these API docs are valuable. If they aren't being used much, I can dig into the why.

[goodroot]

Very helpful -- thank you! I am gathering very broad information and will circle back. 🕺

[goodroot]

@goodroot FYI for future.