[api-docs] follow the correct schema for frontmatter (elastic#138348)

* [api-docs] follow the correct schema for frontmatter * rename non-generated summary: usage * fix yaml comment syntax
neptunian · Aug 10, 2022 · 6c438b3 · 6c438b3
1 parent e49c864
commit 6c438b3
Show file tree

Hide file tree

Showing 93 changed files with 138 additions and 112 deletions.
diff --git a/STYLEGUIDE.mdx b/STYLEGUIDE.mdx
@@ -2,7 +2,7 @@
 id: kibStyleGuide
 slug: /kibana-dev-docs/contributing/styleguide
 title: Style Guide
-summary: JavaScript/TypeScript styleguide.
+description: JavaScript/TypeScript styleguide.
 date: 2021-05-06
 tags: ['kibana', 'onboarding', 'dev', 'styleguide', 'typescript', 'javascript']
 ---

diff --git a/dev_docs/contributing/best_practices.mdx b/dev_docs/contributing/best_practices.mdx
@@ -2,7 +2,7 @@
 id: kibBestPractices
 slug: /kibana-dev-docs/contributing/best-practices
 title: Best practices
-summary: Best practices to follow when building a Kibana plugin.
+description: Best practices to follow when building a Kibana plugin.
 date: 2021-03-17
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/contributing/code_walkthrough.mdx b/dev_docs/contributing/code_walkthrough.mdx
@@ -2,7 +2,7 @@
 id: kibRepoStructure
 slug: /kibana-dev-docs/contributing/repo-structure
 title: Repository structure
-summary: High level walk-through of our repository structure.
+description: High level walk-through of our repository structure.
 date: 2021-10-07
 tags: ['contributor', 'dev', 'github', 'getting started', 'onboarding', 'kibana']
 ---

diff --git a/dev_docs/contributing/dev_principles.mdx b/dev_docs/contributing/dev_principles.mdx
@@ -2,7 +2,7 @@
 id: kibDevPrinciples
 slug: /kibana-dev-docs/contributing/dev-principles
 title: Developer principles
-summary: Follow our development principles to help keep our code base stable, maintainable and scalable.
+description: Follow our development principles to help keep our code base stable, maintainable and scalable.
 date: 2021-03-04
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/contributing/documentation.mdx b/dev_docs/contributing/documentation.mdx
@@ -2,7 +2,7 @@
 id: kibDocumentation
 slug: /kibana-dev-docs/contributing/documentation
 title: Documentation
-summary: Writing documentation during development
+description: Writing documentation during development
 date: 2022-03-01
 tags: ['kibana', 'onboarding', 'dev']
 ---

diff --git a/dev_docs/contributing/how_we_use_github.mdx b/dev_docs/contributing/how_we_use_github.mdx
@@ -2,7 +2,7 @@
 id: kibGitHub
 slug: /kibana-dev-docs/contributing/github
 title: How we use Github
-summary: Forking, branching, committing and using labels in the Kibana GitHub repo
+description: Forking, branching, committing and using labels in the Kibana GitHub repo
 date: 2021-09-16
 tags: ['contributor', 'dev', 'github', 'getting started', 'onboarding', 'kibana']
 ---

diff --git a/dev_docs/contributing/standards.mdx b/dev_docs/contributing/standards.mdx
@@ -2,7 +2,7 @@
 id: kibStandards
 slug: /kibana-dev-docs/standards
 title: Standards and guidelines
-summary: Standards and guidelines we expect every Kibana developer to abide by
+description: Standards and guidelines we expect every Kibana developer to abide by
 date: 2021-09-28
 tags: ['contributor', 'dev', 'github', 'getting started', 'onboarding', 'kibana']
 ---

diff --git a/dev_docs/getting_started/dev_welcome.mdx b/dev_docs/getting_started/dev_welcome.mdx
@@ -2,7 +2,7 @@
 id: kibDevDocsWelcome
 slug: /kibana-dev-docs/getting-started/welcome
 title: Welcome
-summary: Build custom solutions and applications on top of Kibana.
+description: Build custom solutions and applications on top of Kibana.
 date: 2021-01-02
 tags: ['kibana', 'dev', 'contributor']
 ---

diff --git a/dev_docs/getting_started/hello_world_plugin.mdx b/dev_docs/getting_started/hello_world_plugin.mdx
@@ -2,7 +2,7 @@
 id: kibHelloWorldApp
 slug: /kibana-dev-docs/getting-started/hello-world-app
 title: Hello World
-summary: Build a very basic plugin that registers an application that says "Hello World!".
+description: Build a very basic plugin that registers an application that says "Hello World!".
 date: 2021-08-03
 tags: ['kibana', 'dev', 'contributor', 'tutorials']
 ---

diff --git a/dev_docs/getting_started/setting_up_a_development_env.mdx b/dev_docs/getting_started/setting_up_a_development_env.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialSetupDevEnv
 slug: /kibana-dev-docs/getting-started/setup-dev-env
 title: Set up a Development Environment
-summary: Learn how to setup a development environment for contributing to the Kibana repository
+description: Learn how to setup a development environment for contributing to the Kibana repository
 date: 2022-07-07
 tags: ['kibana', 'onboarding', 'dev', 'architecture', 'setup']
 ---

diff --git a/dev_docs/getting_started/troubleshooting.mdx b/dev_docs/getting_started/troubleshooting.mdx
@@ -2,7 +2,7 @@
 id: kibTroubleshooting
 slug: /kibana-dev-docs/getting-started/troubleshooting
 title: Troubleshooting
-summary: A collection of tips for working around strange issues.
+description: A collection of tips for working around strange issues.
 date: 2021-09-08
 tags: ['kibana', 'onboarding', 'dev', 'troubleshooting']
 ---

diff --git a/dev_docs/key_concepts/anatomy_of_a_plugin.mdx b/dev_docs/key_concepts/anatomy_of_a_plugin.mdx
@@ -2,7 +2,7 @@
 id: kibDevAnatomyOfAPlugin
 slug: /kibana-dev-docs/key-concepts/anatomy-of-a-plugin
 title: Anatomy of a plugin
-summary: Anatomy of a Kibana plugin.
+description: Anatomy of a Kibana plugin.
 date: 2021-08-03
 tags: ['kibana', 'onboarding', 'dev']
 ---

diff --git a/dev_docs/key_concepts/audit_logging.mdx b/dev_docs/key_concepts/audit_logging.mdx
@@ -2,7 +2,7 @@
 id: kibAuditLogging
 slug: /kibana-dev-docs/key-concepts/audit-logging
 title: Audit Logging
-summary: Audit Logging
+description: Audit Logging
 date: 2022-06-15
 tags: ['kibana', 'onboarding', 'dev', 'logging', 'audit']
 ---

diff --git a/dev_docs/key_concepts/building_blocks.mdx b/dev_docs/key_concepts/building_blocks.mdx
@@ -2,7 +2,7 @@
 id: kibBuildingBlocks
 slug: /kibana-dev-docs/key-concepts/building-blocks
 title: Building blocks
-summary: Consider these building blocks when developing your plugin.
+description: Consider these building blocks when developing your plugin.
 date: 2021-02-24
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/key_concepts/data_views.mdx b/dev_docs/key_concepts/data_views.mdx
@@ -2,7 +2,7 @@
 id: kibDataViewsKeyConcepts
 slug: /kibana-dev-docs/key-concepts/data-view-intro
 title: Data Views
-summary: Data views are the central method of defining queryable data sets in Kibana
+description: Data views are the central method of defining queryable data sets in Kibana
 date: 2021-08-11
 tags: ['kibana', 'dev', 'contributor', 'api docs']
 ---

diff --git a/dev_docs/key_concepts/embeddables.mdx b/dev_docs/key_concepts/embeddables.mdx
@@ -2,7 +2,7 @@
 id: kibDevDocsEmbeddables
 slug: /kibana-dev-docs/key-concepts/embeddables
 title: Embeddables
-summary: Embeddables provide a way to expose a reusable widget.
+description: Embeddables provide a way to expose a reusable widget.
 date: 2022-07-27
 tags: ['kibana', 'dev', 'contributor', 'api docs']
 ---

diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx
@@ -2,7 +2,7 @@
 id: kibPlatformIntro
 slug: /kibana-dev-docs/key-concepts/platform-intro
 title: Plugins, packages, and the platform
-summary: An introduction to the Kibana platform and how to use it to build a plugin.
+description: An introduction to the Kibana platform and how to use it to build a plugin.
 date: 2021-01-06
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/key_concepts/navigation.mdx b/dev_docs/key_concepts/navigation.mdx
@@ -2,7 +2,7 @@
 id: kibDevKeyConceptsNavigation
 slug: /kibana-dev-docs/routing-and-navigation
 title: Routing, Navigation and URL
-summary: Learn best practices about navigation inside Kibana
+description: Learn best practices about navigation inside Kibana
 date: 2021-10-05
 tags: ['kibana', 'dev', 'architecture', 'contributor']
 ---

diff --git a/dev_docs/key_concepts/performance.mdx b/dev_docs/key_concepts/performance.mdx
@@ -2,7 +2,7 @@
 id: kibDevPerformance
 slug: /kibana-dev-docs/key-concepts/performance
 title: Performance
-summary: Performance tips for Kibana development.
+description: Performance tips for Kibana development.
 date: 2021-12-03
 tags: ['kibana', 'onboarding', 'dev', 'performance']
 ---

diff --git a/dev_docs/key_concepts/persistable_state.mdx b/dev_docs/key_concepts/persistable_state.mdx
@@ -2,7 +2,7 @@
 id: kibDevDocsPersistableStateIntro
 slug: /kibana-dev-docs/key-concepts/persistable-state-intro
 title: Persistable State
-summary: Persitable state is a key concept to understand when building a Kibana plugin.
+description: Persitable state is a key concept to understand when building a Kibana plugin.
 date: 2021-02-02
 tags: ['kibana', 'dev', 'contributor', 'api docs']
 ---

diff --git a/dev_docs/key_concepts/saved_objects.mdx b/dev_docs/key_concepts/saved_objects.mdx
@@ -2,7 +2,7 @@
 id: kibDevDocsSavedObjectsIntro
 slug: /kibana-dev-docs/key-concepts/saved-objects-intro
 title: Saved Objects
-summary: Saved Objects are a key concept to understand when building a Kibana plugin.
+description: Saved Objects are a key concept to understand when building a Kibana plugin.
 date: 2021-02-02
 tags: ['kibana', 'dev', 'contributor', 'api docs']
 ---

diff --git a/dev_docs/tutorials/advanced_settings.mdx b/dev_docs/tutorials/advanced_settings.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialAdvancedSettings
 slug: /kibana-dev-docs/tutorials/advanced-settings
 title: How to register a new advanced setting
-summary: Learn how to add and use a new advanced setting
+description: Learn how to add and use a new advanced setting
 date: 2022-02-07
 tags: ['kibana','onboarding', 'dev', 'architecture', 'tutorials']
 ---

diff --git a/dev_docs/tutorials/building_a_kibana_distributable.mdx b/dev_docs/tutorials/building_a_kibana_distributable.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialBuildingDistributable
 slug: /kibana-dev-docs/tutorials/building-distributable
 title: Building a Kibana distributable
-summary: Learn how to build a Kibana distributable
+description: Learn how to build a Kibana distributable
 date: 2021-05-10
 tags: ['kibana', 'onboarding', 'dev', 'tutorials', 'build', 'distributable']
 ---

diff --git a/dev_docs/tutorials/ci.mdx b/dev_docs/tutorials/ci.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialCI
 slug: /kibana-dev-docs/tutorials/ci
 title: CI
-summary: CI
+description: CI
 date: 2022-02-03
 tags: ['kibana', 'onboarding', 'dev', 'ci']
 ---

diff --git a/dev_docs/tutorials/data/search.mdx b/dev_docs/tutorials/data/search.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialDataSearchAndSessions
 slug: /kibana-dev-docs/tutorials/data/search-and-sessions
 title: Kibana data.search Services
-summary: Kibana Search Services
+description: Kibana Search Services
 date: 2021-02-10
 tags: ['kibana', 'onboarding', 'dev', 'tutorials', 'search', 'sessions', 'search-sessions']
 ---

diff --git a/dev_docs/tutorials/data_views.mdx b/dev_docs/tutorials/data_views.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialDataViews
 slug: /kibana-dev-docs/tutorials/data-views
 title: Data views API
-summary: Data views API
+description: Data views API
 date: 2021-08-11
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/tutorials/debugging.mdx b/dev_docs/tutorials/debugging.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialDebugging
 slug: /kibana-dev-docs/tutorials/debugging
 title: Debugging in development
-summary: Learn how to debug Kibana while running from source
+description: Learn how to debug Kibana while running from source
 date: 2021-04-26
 tags: ['kibana', 'onboarding', 'dev', 'tutorials', 'debugging']
 ---

diff --git a/dev_docs/tutorials/development_windows.mdx b/dev_docs/tutorials/development_windows.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialSetupWindowsDevWSL
 slug: /kibana-dev-docs/tutorial/setup-windows-development-wsl
 title: WSL on Windows Development
-summary: Learn how to setup a Windows development environment using WSL
+description: Learn how to setup a Windows development environment using WSL
 date: 2022-07-07
 tags: ['kibana', 'onboarding', 'setup', 'windows', 'development', 'wsl']
 ---

diff --git a/dev_docs/tutorials/endpoints.mdx b/dev_docs/tutorials/endpoints.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialServerEndpoint
 slug: /kibana-dev-docs/tutorials/registering-endpoints
 title: Registering and accessing an endpoint
-summary: Learn how to register a new endpoint and access it
+description: Learn how to register a new endpoint and access it
 date: 2021-11-24
 tags: ['kibana', 'dev', 'architecture', 'tutorials']
 ---

diff --git a/dev_docs/tutorials/expressions.mdx b/dev_docs/tutorials/expressions.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialExpressions
 slug: /kibana-dev-docs/tutorials/expressions
 title: Kibana Expressions Service
-summary: Kibana Expressions Service
+description: Kibana Expressions Service
 date: 2021-06-01
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/tutorials/kibana_page_template.mdx b/dev_docs/tutorials/kibana_page_template.mdx
@@ -2,7 +2,7 @@
 id: kibDevDocsKPTTutorial
 slug: /kibana-dev-docs/tutorials/kibana-page-template
 title: Kibana Page Template
-summary: Learn how to create pages in Kibana
+description: Learn how to create pages in Kibana
 date: 2021-03-20
 tags: ['kibana', 'dev', 'ui', 'tutorials']
 ---

diff --git a/dev_docs/tutorials/saved_objects.mdx b/dev_docs/tutorials/saved_objects.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialSavedObject
 slug: /kibana-dev-docs/tutorials/saved-objects
 title: Register a new saved object type
-summary: Learn how to register a new saved object type.
+description: Learn how to register a new saved object type.
 date: 2021-02-05
 tags: ['kibana','onboarding', 'dev', 'architecture', 'tutorials']
 ---

diff --git a/dev_docs/tutorials/screenshotting.mdx b/dev_docs/tutorials/screenshotting.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialScreenshotting
 slug: /kibana-dev-docs/tutorials/screenshotting
 title: Kibana Screenshotting Service
-summary: Kibana Screenshotting Service
+description: Kibana Screenshotting Service
 date: 2022-04-12
 tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---

diff --git a/dev_docs/tutorials/submit_a_pull_request.mdx b/dev_docs/tutorials/submit_a_pull_request.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialSubmitPullRequest
 slug: /kibana-dev-docs/tutorials/submit-pull-request
 title: Submitting a Kibana pull request
-summary: Learn how to submit a Kibana pull request
+description: Learn how to submit a Kibana pull request
 date: 2021-06-24
 tags: ['kibana', 'onboarding', 'dev', 'tutorials', 'github', 'pr', 'pull request', 'ci']
 ---

diff --git a/dev_docs/tutorials/testing_plugins.mdx b/dev_docs/tutorials/testing_plugins.mdx
@@ -2,7 +2,7 @@
 id: kibDevTutorialTestingPlugins
 slug: /kibana-dev-docs/tutorials/testing-plugins
 title: Testing Kibana Plugins
-summary: Learn how to test different aspects of Kibana plugins
+description: Learn how to test different aspects of Kibana plugins
 date: 2021-07-05
 tags: ['kibana', 'onboarding', 'dev', 'architecture', 'testing']
 ---

diff --git a/packages/home/sample_data_card/README.mdx b/packages/home/sample_data_card/README.mdx
@@ -2,7 +2,7 @@
 id: home/SampleData/Cards
 slug: /home/sample-data/cards
 title: Sample Data Cards
-summary: A component that displays Sample Data Sets as cards and grid of cards.
+description: A component that displays Sample Data Sets as cards and grid of cards.
 tags: ['home', 'component', 'sample-data']
 date: 2022-06-30
 ---

diff --git a/packages/home/sample_data_tab/README.mdx b/packages/home/sample_data_tab/README.mdx
@@ -2,7 +2,7 @@
 id: home/SampleData/Tab
 slug: /home/sample-data/tab
 title: Sample Data Tab
-summary: A component that displays the content of the Sample Data tab in the `home` plugin.
+description: A component that displays the content of the Sample Data tab in the `home` plugin.
 tags: ['home', 'component', 'sample-data']
 date: 2022-06-30
 ---

diff --git a/packages/kbn-docs-utils/src/api_docs/auto_generated_warning.ts b/packages/kbn-docs-utils/src/api_docs/auto_generated_warning.ts
@@ -0,0 +1,12 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export const AUTO_GENERATED_WARNING = `####
+#### This document is auto-generated and is meant to be viewed inside our experimental, new docs system.
+#### Reach out in #docs-engineering for more info.
+####`;
diff --git a/packages/kbn-docs-utils/src/api_docs/mdx/write_deprecations_doc_by_api.ts b/packages/kbn-docs-utils/src/api_docs/mdx/write_deprecations_doc_by_api.ts
@@ -17,6 +17,7 @@ import {
   ReferencedDeprecationsByPlugin,
   UnreferencedDeprecationsByPlugin,
 } from '../types';
+import { AUTO_GENERATED_WARNING } from '../auto_generated_warning';
 import { getPluginApiDocId } from '../utils';
 
 export function writeDeprecationDocByApi(
@@ -76,18 +77,18 @@ export function writeDeprecationDocByApi(
 
   const mdx = dedent(`
 ---
+${AUTO_GENERATED_WARNING}
 id: kibDevDocsDeprecationsByApi
 slug: /kibana-dev-docs/api-meta/deprecated-api-list-by-api
 title: Deprecated API usage by API
-summary: A list of deprecated APIs, which plugins are still referencing them, and when they need to be removed by.
+description: A list of deprecated APIs, which plugins are still referencing them, and when they need to be removed by.
 date: ${moment().format('YYYY-MM-DD')}
 tags: ['contributor', 'dev', 'apidocs', 'kibana']
-warning: This document is auto-generated and is meant to be viewed inside our experimental, new docs system.
 ---
 
 ## Referenced deprecated APIs
 
-${tableMdx}   
+${tableMdx}
 
 ## Unreferenced deprecated APIs