From d6a84a92c2a47635a6c0da6d10662d16b46da4cd Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Mon, 24 Aug 2020 14:16:59 -0400 Subject: [PATCH] Add asciidoc support for generated plugin list (#72292) (#75778) * add asciidoc support for generated plugin list Try level offset "=+2" instead of "=+1" to stop the inlining of the includes. remove +2 back to +1 * Remove asciidoc, switch to regex. Rearrange dev guide to avoid nesting limit. * Add tests for regex * add a description to not throw off the table. Remove the heading from the paragraph snippet. * Fix more READMEs so table renders correctly * Update plugin list * Remove code-exploration file, moved to plugin-list * fix typo * Add link to developer examples * Update plugin list * fix typo # Conflicts: # docs/developer/architecture/code-exploration.asciidoc --- .../src/test/prChanges.groovy | 2 +- .../architecture/code-exploration.asciidoc | 593 ------------------ docs/developer/architecture/index.asciidoc | 2 - docs/developer/best-practices/index.asciidoc | 2 +- docs/developer/getting-started/index.asciidoc | 2 +- docs/developer/index.asciidoc | 3 + docs/developer/plugin-list.asciidoc | 497 +++++++++++++++ .../src/plugin_list/discover_plugins.ts | 20 +- .../plugin_list/extract_asciidoc_info.test.ts | 86 +++ .../src/plugin_list/extract_asciidoc_info.ts | 32 + .../src/plugin_list/generate_plugin_list.ts | 55 +- .../src/plugin_list/run_plugin_list_cli.ts | 5 +- vars/prChanges.groovy | 2 +- .../dashboard_enhanced/README.asciidoc | 5 + x-pack/plugins/dashboard_enhanced/README.md | 1 - x-pack/plugins/grokdebugger/README.md | 0 x-pack/plugins/ui_actions_enhanced/README.md | 2 + 17 files changed, 681 insertions(+), 628 deletions(-) delete mode 100644 docs/developer/architecture/code-exploration.asciidoc create mode 100644 docs/developer/plugin-list.asciidoc create mode 100644 packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.test.ts create mode 100644 packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.ts create mode 100644 x-pack/plugins/dashboard_enhanced/README.asciidoc delete mode 100644 x-pack/plugins/dashboard_enhanced/README.md delete mode 100644 x-pack/plugins/grokdebugger/README.md diff --git a/.ci/pipeline-library/src/test/prChanges.groovy b/.ci/pipeline-library/src/test/prChanges.groovy index 0f354e7687246..e3f82e6102acc 100644 --- a/.ci/pipeline-library/src/test/prChanges.groovy +++ b/.ci/pipeline-library/src/test/prChanges.groovy @@ -90,7 +90,7 @@ class PrChangesTest extends KibanaBasePipelineTest { props([ githubPrs: [ getChanges: { [ - [filename: 'docs/developer/architecture/code-exploration.asciidoc'], + [filename: 'docs/developer/plugin-list.asciidoc'], ] }, ], ]) diff --git a/docs/developer/architecture/code-exploration.asciidoc b/docs/developer/architecture/code-exploration.asciidoc deleted file mode 100644 index 2f1944a4f03d0..0000000000000 --- a/docs/developer/architecture/code-exploration.asciidoc +++ /dev/null @@ -1,593 +0,0 @@ -//// - -NOTE: - This is an automatically generated file. Please do not edit directly. Instead, run the - following from within the kibana repository: - - node scripts/build_plugin_list_docs - - You can update the template within packages/kbn-dev-utils/target/plugin_list/generate_plugin_list.js - -//// - -[[code-exploration]] -== Exploring Kibana code - -The goals of our folder heirarchy are: - -- Easy for developers to know where to add new services, plugins and applications. -- Easy for developers to know where to find the code from services, plugins and applications. -- Easy to browse and understand our folder structure. - -To that aim, we strive to: - -- Avoid too many files in any given folder. -- Choose clear, unambigious folder names. -- Organize by domain. -- Every folder should contain a README that describes the contents of that folder. - -[discrete] -[[kibana-services-applications]] -=== Services and Applications - -[discrete] -==== src/plugins - -- {kib-repo}blob/{branch}/src/plugins/advanced_settings[advancedSettings] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/apm_oss[apmOss] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/bfetch/README.md[bfetch] - -bfetch allows to batch HTTP requests and streams responses back. - - -- {kib-repo}blob/{branch}/src/plugins/charts/README.md[charts] - -The Charts plugin is a way to create easier integration of shared colors, themes, types and other utilities across all Kibana charts and visualizations. - - -- {kib-repo}blob/{branch}/src/plugins/console[console] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/dashboard/README.md[dashboard] - -Contains the dashboard application. - - -- {kib-repo}blob/{branch}/src/plugins/data/README.md[data] - -data plugin provides common data access services. - - -- {kib-repo}blob/{branch}/src/plugins/dev_tools/README.md[devTools] - -The ui/registry/dev_tools is removed in favor of the devTools plugin which exposes a register method in the setup contract. -Registering app works mostly the same as registering apps in core.application.register. -Routing will be handled by the id of the dev tool - your dev tool will be mounted when the URL matches /app/dev_tools#/. -This API doesn't support angular, for registering angular dev tools, bootstrap a local module on mount into the given HTML element. - - -- {kib-repo}blob/{branch}/src/plugins/discover/README.md[discover] - -Contains the Discover application and the saved search embeddable. - - -- {kib-repo}blob/{branch}/src/plugins/embeddable/README.md[embeddable] - -Embeddables are re-usable widgets that can be rendered in any environment or plugin. Developers can embed them directly in their plugin. End users can dynamically add them to any embeddable containers. - - -- {kib-repo}blob/{branch}/src/plugins/es_ui_shared[esUiShared] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/expressions/README.md[expressions] - -This plugin provides methods which will parse & execute an expression pipeline -string for you, as well as a series of registries for advanced users who might -want to incorporate their own functions, types, and renderers into the service -for use in their own application. - - -- {kib-repo}blob/{branch}/src/plugins/home/README.md[home] - -Moves the legacy ui/registry/feature_catalogue module for registering "features" that should be shown in the home page's feature catalogue to a service within a "home" plugin. The feature catalogue refered to here should not be confused with the "feature" plugin for registering features used to derive UI capabilities for feature controls. - - -- {kib-repo}blob/{branch}/src/plugins/index_pattern_management[indexPatternManagement] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/input_control_vis/README.md[inputControlVis] - -Contains the input control visualization allowing to place custom filter controls on a dashboard. - - -- {kib-repo}blob/{branch}/src/plugins/inspector/README.md[inspector] - -The inspector is a contextual tool to gain insights into different elements -in Kibana, e.g. visualizations. It has the form of a flyout panel. - - -- {kib-repo}blob/{branch}/src/plugins/kibana_legacy/README.md[kibanaLegacy] - -This plugin will contain several helpers and services to integrate pieces of the legacy Kibana app with the new Kibana platform. - - -- {kib-repo}blob/{branch}/src/plugins/kibana_react/README.md[kibanaReact] - -Tools for building React applications in Kibana. - - -- {kib-repo}blob/{branch}/src/plugins/kibana_usage_collection/README.md[kibanaUsageCollection] - -This plugin registers the basic usage collectors from Kibana: - - -- {kib-repo}blob/{branch}/src/plugins/kibana_utils/README.md[kibanaUtils] - -Utilities for building Kibana plugins. - - -- {kib-repo}blob/{branch}/src/plugins/legacy_export[legacyExport] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/management[management] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/maps_legacy[mapsLegacy] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/navigation/README.md[navigation] - -The navigation plugins exports the TopNavMenu component. -It also provides a stateful version of it on the start contract. - - -- {kib-repo}blob/{branch}/src/plugins/newsfeed[newsfeed] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/region_map[regionMap] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/saved_objects[savedObjects] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/saved_objects_management[savedObjectsManagement] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/share/README.md[share] - -Replaces the legacy ui/share module for registering share context menus. - - -- {kib-repo}blob/{branch}/src/plugins/telemetry/README.md[telemetry] - -Telemetry allows Kibana features to have usage tracked in the wild. The general term "telemetry" refers to multiple things: - - -- {kib-repo}blob/{branch}/src/plugins/telemetry_collection_manager/README.md[telemetryCollectionManager] - -Telemetry's collection manager to go through all the telemetry sources when fetching it before reporting. - - -- {kib-repo}blob/{branch}/src/plugins/telemetry_management_section/README.md[telemetryManagementSection] - -This plugin adds the Advanced Settings section for the Usage Data collection (aka Telemetry). - - -- {kib-repo}blob/{branch}/src/plugins/tile_map[tileMap] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/src/plugins/timelion/README.md[timelion] - -Contains the deprecated timelion application. For the timelion visualization, -which also contains the timelion APIs and backend, look at the vis_type_timelion plugin. - - -- {kib-repo}blob/{branch}/src/plugins/ui_actions/README.md[uiActions] - -An API for: - - -- {kib-repo}blob/{branch}/src/plugins/usage_collection/README.md[usageCollection] - -Usage Collection allows collecting usage data for other services to consume (telemetry and monitoring). -To integrate with the telemetry services for usage collection of your feature, there are 2 steps: - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_markdown/README.md[visTypeMarkdown] - -The markdown visualization that can be used to place text panels on dashboards. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_metric/README.md[visTypeMetric] - -Contains the metric visualization. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_table/README.md[visTypeTable] - -Contains the data table visualization, that allows presenting data in a simple table format. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_tagcloud/README.md[visTypeTagcloud] - -Contains the tagcloud visualization. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_timelion/README.md[visTypeTimelion] - -Contains the timelion visualization and the timelion backend. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_timeseries/README.md[visTypeTimeseries] - -Contains everything around TSVB (the editor, visualizatin implementations and backends). - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_vega/README.md[visTypeVega] - -Contains the Vega visualization. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_vislib/README.md[visTypeVislib] - -Contains the vislib visualizations. These are the classical area/line/bar, pie, gauge/goal and -heatmap charts. - - -- {kib-repo}blob/{branch}/src/plugins/vis_type_xy/README.md[visTypeXy] - -Contains the new xy-axis chart using the elastic-charts library, which will eventually -replace the vislib xy-axis (bar, area, line) charts. - - -- {kib-repo}blob/{branch}/src/plugins/visualizations/README.md[visualizations] - -Contains most of the visualization infrastructure, e.g. the visualization type registry or the -visualization embeddable. - - -- {kib-repo}blob/{branch}/src/plugins/visualize/README.md[visualize] - -Contains the visualize application which includes the listing page and the app frame, -which will load the visualization's editor. - - -[discrete] -==== x-pack/plugins - -- {kib-repo}blob/{branch}/x-pack/plugins/actions/README.md[actions] - -The Kibana actions plugin provides a framework to create executable actions. You can: - - -- {kib-repo}blob/{branch}/x-pack/plugins/alerting_builtins/README.md[alertingBuiltins] - -This plugin provides alertTypes shipped with Kibana for use with the -the alerts plugin. When enabled, it will register -the built-in alertTypes with the alerting plugin, register associated HTTP -routes, etc. - - -- {kib-repo}blob/{branch}/x-pack/plugins/alerts/README.md[alerts] - -The Kibana alerting plugin provides a common place to set up alerts. You can: - - -- {kib-repo}blob/{branch}/x-pack/plugins/apm/readme.md[apm] - -To access an elasticsearch instance that has live data you have two options: - - -- {kib-repo}blob/{branch}/x-pack/plugins/audit_trail[auditTrail] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/beats_management/readme.md[beatsManagement] - -Notes: -Failure to have auth enabled in Kibana will make for a broken UI. UI-based errors not yet in place - - -- {kib-repo}blob/{branch}/x-pack/plugins/canvas/README.md[canvas] - -"Never look back. The past is done. The future is a blank canvas." ― Suzy Kassem, Rise Up and Salute the Sun - - -- {kib-repo}blob/{branch}/x-pack/plugins/case/README.md[case] - -Experimental Feature - - -- {kib-repo}blob/{branch}/x-pack/plugins/cloud[cloud] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/code[code] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/console_extensions[consoleExtensions] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/cross_cluster_replication/README.md[crossClusterReplication] - -You can run a local cluster and simulate a remote cluster within a single Kibana directory. - - -- {kib-repo}blob/{branch}/x-pack/plugins/dashboard_enhanced/README.md[dashboardEnhanced] - -Contains the enhancements to the OSS dashboard app. - - -- {kib-repo}blob/{branch}/x-pack/plugins/dashboard_mode/README.md[dashboardMode] - -The deprecated dashboard only mode. - - -- {kib-repo}blob/{branch}/x-pack/plugins/data_enhanced[dataEnhanced] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/discover_enhanced/README.md[discoverEnhanced] - -Contains the enhancements to the OSS discover app. - - -- {kib-repo}blob/{branch}/x-pack/plugins/embeddable_enhanced[embeddableEnhanced] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/encrypted_saved_objects/README.md[encryptedSavedObjects] - -The purpose of this plugin is to provide a way to encrypt/decrypt attributes on the custom Saved Objects that works with -security and spaces filtering as well as performing audit logging. - - -- {kib-repo}blob/{branch}/x-pack/plugins/enterprise_search/README.md[enterpriseSearch] - -This plugin's goal is to provide a Kibana user interface to the Enterprise Search solution's products (App Search and Workplace Search). In it's current MVP state, the plugin provides the following with the goal of gathering user feedback and raising product awareness: - - -- {kib-repo}blob/{branch}/x-pack/plugins/event_log/README.md[eventLog] - -The purpose of this plugin is to provide a way to persist a history of events -occuring in Kibana, initially just for the Make It Action project - alerts -and actions. - - -- {kib-repo}blob/{branch}/x-pack/plugins/features[features] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/file_upload[fileUpload] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/global_search/README.md[globalSearch] - -The GlobalSearch plugin provides an easy way to search for various objects, such as applications -or dashboards from the Kibana instance, from both server and client-side plugins - - -- {kib-repo}blob/{branch}/x-pack/plugins/global_search_providers[globalSearchProviders] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/graph/README.md[graph] - -This is the main source folder of the Graph plugin. It contains all of the Kibana server and client source code. x-pack/test/functional/apps/graph contains additional functional tests. - - -- {kib-repo}blob/{branch}/x-pack/plugins/grokdebugger/README.md[grokdebugger] - -- {kib-repo}blob/{branch}/x-pack/plugins/index_lifecycle_management/README.md[indexLifecycleManagement] - -You can test that the Frozen badge, phase filtering, and lifecycle information is surfaced in -Index Management by running this series of requests in Console: - - -- {kib-repo}blob/{branch}/x-pack/plugins/index_management/README.md[indexManagement] - -Create a data stream using Console and you'll be able to view it in the UI: - - -- {kib-repo}blob/{branch}/x-pack/plugins/infra/README.md[infra] - -This is the home of the infra plugin, which aims to provide a solution for -the infrastructure monitoring use-case within Kibana. - - -- {kib-repo}blob/{branch}/x-pack/plugins/ingest_manager/README.md[ingestManager] - -Fleet needs to have Elasticsearch API keys enabled, and also to have TLS enabled on kibana, (if you want to run Kibana without TLS you can provide the following config flag --xpack.ingestManager.fleet.tlsCheckDisabled=false) - - -- {kib-repo}blob/{branch}/x-pack/plugins/ingest_pipelines/README.md[ingestPipelines] - -The ingest_pipelines plugin provides Kibana support for Elasticsearch's ingest nodes. Please refer to the Elasticsearch documentation for more details. - - -- {kib-repo}blob/{branch}/x-pack/plugins/lens/readme.md[lens] - -Run all tests from the x-pack root directory - - -- {kib-repo}blob/{branch}/x-pack/plugins/license_management[licenseManagement] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/licensing/README.md[licensing] - -The licensing plugin retrieves license data from Elasticsearch at regular configurable intervals. - - -- {kib-repo}blob/{branch}/x-pack/plugins/lists/README.md[lists] - -README.md for developers working on the backend lists on how to get started -using the CURL scripts in the scripts folder. - - -- {kib-repo}blob/{branch}/x-pack/plugins/logstash[logstash] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/maps/README.md[maps] - -Visualize geo data from Elasticsearch or 3rd party geo-services. - - -- {kib-repo}blob/{branch}/x-pack/plugins/maps_legacy_licensing/README.md[mapsLegacyLicensing] - -This plugin provides access to the detailed tile map services from Elastic. - - -- {kib-repo}blob/{branch}/x-pack/plugins/ml[ml] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/monitoring[monitoring] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/observability/README.md[observability] - -This plugin provides shared components and services for use across observability solutions, as well as the observability landing page UI. - - -- {kib-repo}blob/{branch}/x-pack/plugins/oss_telemetry[ossTelemetry] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/painless_lab[painlessLab] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/remote_clusters[remoteClusters] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/reporting/README.md[reporting] - -An awesome Kibana reporting plugin - - -- {kib-repo}blob/{branch}/x-pack/plugins/rollup/README.md[rollup] - -Welcome to the Kibana rollup plugin! This plugin provides Kibana support for Elasticsearch's rollup feature. Please refer to the Elasticsearch documentation to understand rollup indices and how to create rollup jobs. - - -- {kib-repo}blob/{branch}/x-pack/plugins/searchprofiler[searchprofiler] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/security/README.md[security] - -See Configuring security in Kibana. - - -- {kib-repo}blob/{branch}/x-pack/plugins/security_solution/README.md[securitySolution] - -Welcome to the Kibana Security Solution plugin! This README will go over getting started with development and testing. - - -- {kib-repo}blob/{branch}/x-pack/plugins/snapshot_restore/README.md[snapshotRestore] - -or - - -- {kib-repo}blob/{branch}/x-pack/plugins/spaces[spaces] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/task_manager[taskManager] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/telemetry_collection_xpack/README.md[telemetryCollectionXpack] - -Gathers all usage collection, retrieving them from both: OSS and X-Pack plugins. - - -- {kib-repo}blob/{branch}/x-pack/plugins/transform[transform] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/translations[translations] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/triggers_actions_ui/README.md[triggers_actions_ui] - -The Kibana alerts and actions UI plugin provides a user interface for managing alerts and actions. -As a developer you can reuse and extend built-in alerts and actions UI functionality: - - -- {kib-repo}blob/{branch}/x-pack/plugins/ui_actions_enhanced/README.md[uiActionsEnhanced] - -- {kib-repo}blob/{branch}/x-pack/plugins/upgrade_assistant[upgradeAssistant] - -WARNING: Missing README. - - -- {kib-repo}blob/{branch}/x-pack/plugins/uptime/README.md[uptime] - -The purpose of this plugin is to provide users of Heartbeat more visibility of what's happening -in their infrastructure. - - -- {kib-repo}blob/{branch}/x-pack/plugins/watcher/README.md[watcher] - -This plugins adopts some conventions in addition to or in place of conventions in Kibana (at the time of the plugin's creation): - diff --git a/docs/developer/architecture/index.asciidoc b/docs/developer/architecture/index.asciidoc index 2e6ab1a4ad6ac..ac25fe003df08 100644 --- a/docs/developer/architecture/index.asciidoc +++ b/docs/developer/architecture/index.asciidoc @@ -17,7 +17,6 @@ A few notable services are called out below. * <> * <> * <> -* <> include::add-data-tutorials.asciidoc[leveloffset=+1] @@ -25,4 +24,3 @@ include::development-visualize-index.asciidoc[leveloffset=+1] include::security/index.asciidoc[leveloffset=+1] -include::code-exploration.asciidoc[leveloffset=+1] diff --git a/docs/developer/best-practices/index.asciidoc b/docs/developer/best-practices/index.asciidoc index 90b0092d835a8..63a44b54d454f 100644 --- a/docs/developer/best-practices/index.asciidoc +++ b/docs/developer/best-practices/index.asciidoc @@ -99,7 +99,7 @@ Re-using these services will help create a consistent experience across [discrete] === Backward compatibility -Eventually we want to garauntee to our plugin developers that their plugins will not break from minor to minor. +Eventually we want to guarantee to our plugin developers that their plugins will not break from minor to minor. Any time you create or change a public API, keep this in mind, and consider potential backward compatibility issues. While we have a formal diff --git a/docs/developer/getting-started/index.asciidoc b/docs/developer/getting-started/index.asciidoc index 2ac51b6cf86f8..eaa35eece5a2c 100644 --- a/docs/developer/getting-started/index.asciidoc +++ b/docs/developer/getting-started/index.asciidoc @@ -99,7 +99,7 @@ preserving data inbetween runs, running remote cluster, etc. [discrete] === Run {kib} -In another terminal window, start up {kib}. Include developer examples by adding an optional `--run-examples` flag. +In another terminal window, start up {kib}. Include {kib-repo}tree/{branch}/examples[developer examples] by adding an optional `--run-examples` flag. [source,bash] ---- diff --git a/docs/developer/index.asciidoc b/docs/developer/index.asciidoc index db57815a1285a..5f032a3952173 100644 --- a/docs/developer/index.asciidoc +++ b/docs/developer/index.asciidoc @@ -12,6 +12,7 @@ running in no time. If you have any problems, file an issue in the https://githu * <> * <> * <> +* <> -- @@ -27,3 +28,5 @@ include::plugin/index.asciidoc[] include::advanced/index.asciidoc[] +include::plugin-list.asciidoc[] + diff --git a/docs/developer/plugin-list.asciidoc b/docs/developer/plugin-list.asciidoc new file mode 100644 index 0000000000000..85dd8ff3b1610 --- /dev/null +++ b/docs/developer/plugin-list.asciidoc @@ -0,0 +1,497 @@ +//// + +NOTE: + This is an automatically generated file. Please do not edit directly. Instead, run the + following from within the kibana repository: + + node scripts/build_plugin_list_docs + + You can update the template within packages/kbn-dev-utils/target/plugin_list/generate_plugin_list.js + +//// + +[[plugin-list]] +== List of {kib} plugins + +[discrete] +=== src/plugins + +[%header,cols=2*] +|=== +|Name +|Description + + +|{kib-repo}blob/{branch}/src/plugins/advanced_settings[advancedSettings] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/apm_oss[apmOss] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/bfetch/README.md[bfetch] +|bfetch allows to batch HTTP requests and streams responses back. + + +|{kib-repo}blob/{branch}/src/plugins/charts/README.md[charts] +|The Charts plugin is a way to create easier integration of shared colors, themes, types and other utilities across all Kibana charts and visualizations. + + +|{kib-repo}blob/{branch}/src/plugins/console[console] +|WARNING: Missing README. + + +|<> +|- Registers the dashboard application. +- Adds a dashboard embeddable that can be used in other applications. + + +|{kib-repo}blob/{branch}/src/plugins/data/README.md[data] +|data plugin provides common data access services. + + +|{kib-repo}blob/{branch}/src/plugins/dev_tools/README.md[devTools] +|The ui/registry/dev_tools is removed in favor of the devTools plugin which exposes a register method in the setup contract. +Registering app works mostly the same as registering apps in core.application.register. +Routing will be handled by the id of the dev tool - your dev tool will be mounted when the URL matches /app/dev_tools#/. +This API doesn't support angular, for registering angular dev tools, bootstrap a local module on mount into the given HTML element. + + +|{kib-repo}blob/{branch}/src/plugins/discover/README.md[discover] +|Contains the Discover application and the saved search embeddable. + + +|{kib-repo}blob/{branch}/src/plugins/embeddable/README.md[embeddable] +|Embeddables are re-usable widgets that can be rendered in any environment or plugin. Developers can embed them directly in their plugin. End users can dynamically add them to any embeddable containers. + + +|{kib-repo}blob/{branch}/src/plugins/es_ui_shared[esUiShared] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/expressions/README.md[expressions] +|This plugin provides methods which will parse & execute an expression pipeline +string for you, as well as a series of registries for advanced users who might +want to incorporate their own functions, types, and renderers into the service +for use in their own application. + + +|{kib-repo}blob/{branch}/src/plugins/home/README.md[home] +|Moves the legacy ui/registry/feature_catalogue module for registering "features" that should be shown in the home page's feature catalogue to a service within a "home" plugin. The feature catalogue refered to here should not be confused with the "feature" plugin for registering features used to derive UI capabilities for feature controls. + + +|{kib-repo}blob/{branch}/src/plugins/index_pattern_management[indexPatternManagement] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/input_control_vis/README.md[inputControlVis] +|Contains the input control visualization allowing to place custom filter controls on a dashboard. + + +|{kib-repo}blob/{branch}/src/plugins/inspector/README.md[inspector] +|The inspector is a contextual tool to gain insights into different elements +in Kibana, e.g. visualizations. It has the form of a flyout panel. + + +|{kib-repo}blob/{branch}/src/plugins/kibana_legacy/README.md[kibanaLegacy] +|This plugin will contain several helpers and services to integrate pieces of the legacy Kibana app with the new Kibana platform. + + +|{kib-repo}blob/{branch}/src/plugins/kibana_react/README.md[kibanaReact] +|Tools for building React applications in Kibana. + + +|{kib-repo}blob/{branch}/src/plugins/kibana_usage_collection/README.md[kibanaUsageCollection] +|This plugin registers the basic usage collectors from Kibana: + + +|{kib-repo}blob/{branch}/src/plugins/kibana_utils/README.md[kibanaUtils] +|Utilities for building Kibana plugins. + + +|{kib-repo}blob/{branch}/src/plugins/legacy_export[legacyExport] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/management[management] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/maps_legacy[mapsLegacy] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/navigation/README.md[navigation] +|The navigation plugins exports the TopNavMenu component. +It also provides a stateful version of it on the start contract. + + +|{kib-repo}blob/{branch}/src/plugins/newsfeed[newsfeed] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/region_map[regionMap] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/saved_objects[savedObjects] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/saved_objects_management[savedObjectsManagement] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/share/README.md[share] +|Replaces the legacy ui/share module for registering share context menus. + + +|{kib-repo}blob/{branch}/src/plugins/telemetry/README.md[telemetry] +|Telemetry allows Kibana features to have usage tracked in the wild. The general term "telemetry" refers to multiple things: + + +|{kib-repo}blob/{branch}/src/plugins/telemetry_collection_manager/README.md[telemetryCollectionManager] +|Telemetry's collection manager to go through all the telemetry sources when fetching it before reporting. + + +|{kib-repo}blob/{branch}/src/plugins/telemetry_management_section/README.md[telemetryManagementSection] +|This plugin adds the Advanced Settings section for the Usage Data collection (aka Telemetry). + + +|{kib-repo}blob/{branch}/src/plugins/tile_map[tileMap] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/src/plugins/timelion/README.md[timelion] +|Contains the deprecated timelion application. For the timelion visualization, +which also contains the timelion APIs and backend, look at the vis_type_timelion plugin. + + +|{kib-repo}blob/{branch}/src/plugins/ui_actions/README.md[uiActions] +|An API for: + + +|{kib-repo}blob/{branch}/src/plugins/usage_collection/README.md[usageCollection] +|Usage Collection allows collecting usage data for other services to consume (telemetry and monitoring). +To integrate with the telemetry services for usage collection of your feature, there are 2 steps: + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_markdown/README.md[visTypeMarkdown] +|The markdown visualization that can be used to place text panels on dashboards. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_metric/README.md[visTypeMetric] +|Contains the metric visualization. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_table/README.md[visTypeTable] +|Contains the data table visualization, that allows presenting data in a simple table format. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_tagcloud/README.md[visTypeTagcloud] +|Contains the tagcloud visualization. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_timelion/README.md[visTypeTimelion] +|Contains the timelion visualization and the timelion backend. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_timeseries/README.md[visTypeTimeseries] +|Contains everything around TSVB (the editor, visualizatin implementations and backends). + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_vega/README.md[visTypeVega] +|Contains the Vega visualization. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_vislib/README.md[visTypeVislib] +|Contains the vislib visualizations. These are the classical area/line/bar, pie, gauge/goal and +heatmap charts. + + +|{kib-repo}blob/{branch}/src/plugins/vis_type_xy/README.md[visTypeXy] +|Contains the new xy-axis chart using the elastic-charts library, which will eventually +replace the vislib xy-axis (bar, area, line) charts. + + +|{kib-repo}blob/{branch}/src/plugins/visualizations/README.md[visualizations] +|Contains most of the visualization infrastructure, e.g. the visualization type registry or the +visualization embeddable. + + +|{kib-repo}blob/{branch}/src/plugins/visualize/README.md[visualize] +|Contains the visualize application which includes the listing page and the app frame, +which will load the visualization's editor. + + +|=== + +[discrete] +=== x-pack/plugins + +[%header,cols=2*] +|=== +|Name +|Description + + +|{kib-repo}blob/{branch}/x-pack/plugins/actions/README.md[actions] +|The Kibana actions plugin provides a framework to create executable actions. You can: + + +|{kib-repo}blob/{branch}/x-pack/plugins/alerting_builtins/README.md[alertingBuiltins] +|This plugin provides alertTypes shipped with Kibana for use with the +the alerts plugin. When enabled, it will register +the built-in alertTypes with the alerting plugin, register associated HTTP +routes, etc. + + +|{kib-repo}blob/{branch}/x-pack/plugins/alerts/README.md[alerts] +|The Kibana alerting plugin provides a common place to set up alerts. You can: + + +|{kib-repo}blob/{branch}/x-pack/plugins/apm/readme.md[apm] +|To access an elasticsearch instance that has live data you have two options: + + +|{kib-repo}blob/{branch}/x-pack/plugins/audit_trail[auditTrail] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/beats_management/readme.md[beatsManagement] +|Notes: +Failure to have auth enabled in Kibana will make for a broken UI. UI-based errors not yet in place + + +|{kib-repo}blob/{branch}/x-pack/plugins/canvas/README.md[canvas] +|"Never look back. The past is done. The future is a blank canvas." ― Suzy Kassem, Rise Up and Salute the Sun + + +|{kib-repo}blob/{branch}/x-pack/plugins/case/README.md[case] +|Experimental Feature + + +|{kib-repo}blob/{branch}/x-pack/plugins/cloud[cloud] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/code[code] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/console_extensions[consoleExtensions] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/cross_cluster_replication/README.md[crossClusterReplication] +|You can run a local cluster and simulate a remote cluster within a single Kibana directory. + + +|<> +|Adds drilldown capabilities to dashboard. Owned by the Kibana App team. + + +|{kib-repo}blob/{branch}/x-pack/plugins/dashboard_mode/README.md[dashboardMode] +|The deprecated dashboard only mode. + + +|{kib-repo}blob/{branch}/x-pack/plugins/data_enhanced[dataEnhanced] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/discover_enhanced/README.md[discoverEnhanced] +|Contains the enhancements to the OSS discover app. + + +|<> +|Enhances Embeddables by registering a custom factory provider. The enhanced factory provider +adds dynamic actions to every embeddables state, in order to support drilldowns. + + +|{kib-repo}blob/{branch}/x-pack/plugins/encrypted_saved_objects/README.md[encryptedSavedObjects] +|The purpose of this plugin is to provide a way to encrypt/decrypt attributes on the custom Saved Objects that works with +security and spaces filtering as well as performing audit logging. + + +|{kib-repo}blob/{branch}/x-pack/plugins/enterprise_search/README.md[enterpriseSearch] +|This plugin's goal is to provide a Kibana user interface to the Enterprise Search solution's products (App Search and Workplace Search). In it's current MVP state, the plugin provides the following with the goal of gathering user feedback and raising product awareness: + + +|{kib-repo}blob/{branch}/x-pack/plugins/event_log/README.md[eventLog] +|The purpose of this plugin is to provide a way to persist a history of events +occuring in Kibana, initially just for the Make It Action project - alerts +and actions. + + +|{kib-repo}blob/{branch}/x-pack/plugins/features[features] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/file_upload[fileUpload] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/global_search/README.md[globalSearch] +|The GlobalSearch plugin provides an easy way to search for various objects, such as applications +or dashboards from the Kibana instance, from both server and client-side plugins + + +|{kib-repo}blob/{branch}/x-pack/plugins/global_search_providers[globalSearchProviders] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/graph/README.md[graph] +|This is the main source folder of the Graph plugin. It contains all of the Kibana server and client source code. x-pack/test/functional/apps/graph contains additional functional tests. + + +|{kib-repo}blob/{branch}/x-pack/plugins/grokdebugger[grokdebugger] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/index_lifecycle_management/README.md[indexLifecycleManagement] +|You can test that the Frozen badge, phase filtering, and lifecycle information is surfaced in +Index Management by running this series of requests in Console: + + +|{kib-repo}blob/{branch}/x-pack/plugins/index_management/README.md[indexManagement] +|Create a data stream using Console and you'll be able to view it in the UI: + + +|{kib-repo}blob/{branch}/x-pack/plugins/infra/README.md[infra] +|This is the home of the infra plugin, which aims to provide a solution for +the infrastructure monitoring use-case within Kibana. + + +|{kib-repo}blob/{branch}/x-pack/plugins/ingest_manager/README.md[ingestManager] +|Fleet needs to have Elasticsearch API keys enabled, and also to have TLS enabled on kibana, (if you want to run Kibana without TLS you can provide the following config flag --xpack.ingestManager.fleet.tlsCheckDisabled=false) + + +|{kib-repo}blob/{branch}/x-pack/plugins/ingest_pipelines/README.md[ingestPipelines] +|The ingest_pipelines plugin provides Kibana support for Elasticsearch's ingest nodes. Please refer to the Elasticsearch documentation for more details. + + +|{kib-repo}blob/{branch}/x-pack/plugins/lens/readme.md[lens] +|Run all tests from the x-pack root directory + + +|{kib-repo}blob/{branch}/x-pack/plugins/license_management[licenseManagement] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/licensing/README.md[licensing] +|The licensing plugin retrieves license data from Elasticsearch at regular configurable intervals. + + +|{kib-repo}blob/{branch}/x-pack/plugins/lists/README.md[lists] +|README.md for developers working on the backend lists on how to get started +using the CURL scripts in the scripts folder. + + +|{kib-repo}blob/{branch}/x-pack/plugins/logstash[logstash] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/maps/README.md[maps] +|Visualize geo data from Elasticsearch or 3rd party geo-services. + + +|{kib-repo}blob/{branch}/x-pack/plugins/maps_legacy_licensing/README.md[mapsLegacyLicensing] +|This plugin provides access to the detailed tile map services from Elastic. + + +|{kib-repo}blob/{branch}/x-pack/plugins/ml[ml] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/monitoring[monitoring] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/observability/README.md[observability] +|This plugin provides shared components and services for use across observability solutions, as well as the observability landing page UI. + + +|{kib-repo}blob/{branch}/x-pack/plugins/oss_telemetry[ossTelemetry] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/painless_lab[painlessLab] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/remote_clusters[remoteClusters] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/reporting/README.md[reporting] +|An awesome Kibana reporting plugin + + +|{kib-repo}blob/{branch}/x-pack/plugins/rollup/README.md[rollup] +|Welcome to the Kibana rollup plugin! This plugin provides Kibana support for Elasticsearch's rollup feature. Please refer to the Elasticsearch documentation to understand rollup indices and how to create rollup jobs. + + +|{kib-repo}blob/{branch}/x-pack/plugins/searchprofiler[searchprofiler] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/security/README.md[security] +|See Configuring security in Kibana. + + +|{kib-repo}blob/{branch}/x-pack/plugins/security_solution/README.md[securitySolution] +|Welcome to the Kibana Security Solution plugin! This README will go over getting started with development and testing. + + +|{kib-repo}blob/{branch}/x-pack/plugins/snapshot_restore/README.md[snapshotRestore] +|or + + +|{kib-repo}blob/{branch}/x-pack/plugins/spaces[spaces] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/task_manager[taskManager] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/telemetry_collection_xpack/README.md[telemetryCollectionXpack] +|Gathers all usage collection, retrieving them from both: OSS and X-Pack plugins. + + +|{kib-repo}blob/{branch}/x-pack/plugins/transform[transform] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/translations[translations] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/triggers_actions_ui/README.md[triggers_actions_ui] +|The Kibana alerts and actions UI plugin provides a user interface for managing alerts and actions. +As a developer you can reuse and extend built-in alerts and actions UI functionality: + + +|{kib-repo}blob/{branch}/x-pack/plugins/ui_actions_enhanced/README.md[uiActionsEnhanced] +|Registers commercially licensed generic actions like per panel time range and contains some code that supports drilldown work. + + +|{kib-repo}blob/{branch}/x-pack/plugins/upgrade_assistant[upgradeAssistant] +|WARNING: Missing README. + + +|{kib-repo}blob/{branch}/x-pack/plugins/uptime/README.md[uptime] +|The purpose of this plugin is to provide users of Heartbeat more visibility of what's happening +in their infrastructure. + + +|{kib-repo}blob/{branch}/x-pack/plugins/watcher/README.md[watcher] +|This plugins adopts some conventions in addition to or in place of conventions in Kibana (at the time of the plugin's creation): + + +|=== + +include::{kibana-root}/src/plugins/dashboard/README.asciidoc[leveloffset=+1] +include::{kibana-root}/x-pack/plugins/dashboard_enhanced/README.asciidoc[leveloffset=+1] +include::{kibana-root}/x-pack/plugins/embeddable_enhanced/README.asciidoc[leveloffset=+1] diff --git a/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts b/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts index 733b9f23a5394..783d584656b17 100644 --- a/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts +++ b/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts @@ -25,12 +25,14 @@ import cheerio from 'cheerio'; import { REPO_ROOT } from '../repo_root'; import { simpleKibanaPlatformPluginDiscovery } from '../simple_kibana_platform_plugin_discovery'; +import { extractAsciidocInfo } from './extract_asciidoc_info'; export interface Plugin { id: string; relativeDir?: string; relativeReadmePath?: string; readmeSnippet?: string; + readmeAsciidocAnchor?: string; } export type Plugins = Plugin[]; @@ -38,14 +40,29 @@ export type Plugins = Plugin[]; const getReadmeName = (directory: string) => Fs.readdirSync(directory).find((name) => name.toLowerCase() === 'readme.md'); +const getReadmeAsciidocName = (directory: string) => + Fs.readdirSync(directory).find((name) => name.toLowerCase() === 'readme.asciidoc'); + export const discoverPlugins = (pluginsRootDir: string): Plugins => simpleKibanaPlatformPluginDiscovery([pluginsRootDir], []).map( ({ directory, manifest: { id } }): Plugin => { const readmeName = getReadmeName(directory); + const readmeAsciidocName = getReadmeAsciidocName(directory); let relativeReadmePath: string | undefined; let readmeSnippet: string | undefined; - if (readmeName) { + let readmeAsciidocAnchor: string | undefined; + + if (readmeAsciidocName) { + const readmePath = Path.resolve(directory, readmeAsciidocName); + relativeReadmePath = Path.relative(REPO_ROOT, readmePath); + + const readmeText = Fs.readFileSync(relativeReadmePath).toString(); + + const { firstParagraph, anchor } = extractAsciidocInfo(readmeText); + readmeSnippet = firstParagraph; + readmeAsciidocAnchor = anchor; + } else if (readmeName) { const readmePath = Path.resolve(directory, readmeName); relativeReadmePath = Path.relative(REPO_ROOT, readmePath); @@ -64,6 +81,7 @@ export const discoverPlugins = (pluginsRootDir: string): Plugins => relativeReadmePath, relativeDir: relativeReadmePath || Path.relative(REPO_ROOT, directory), readmeSnippet, + readmeAsciidocAnchor, }; } ); diff --git a/packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.test.ts b/packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.test.ts new file mode 100644 index 0000000000000..baa88bbe1d2ff --- /dev/null +++ b/packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.test.ts @@ -0,0 +1,86 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { extractAsciidocInfo } from './extract_asciidoc_info'; + +it('Returns the info and anchor when there is only one paragraph', () => { + const { firstParagraph, anchor } = extractAsciidocInfo( + `[[this-is-the-anchor]] +== I'm the heading! + +Hello + +I'm an intro paragraph!` + ); + + expect(firstParagraph).toEqual(`Hello\n\nI'm an intro paragraph!`); + expect(anchor).toEqual('this-is-the-anchor'); +}); + +it('Returns the info and anchor when there are multiple paragraphs without an anchor', () => { + const { firstParagraph, anchor } = extractAsciidocInfo( + `[[this-is-the-anchor]] +== Heading here + +Intro. + +=== Another heading + +More details` + ); + + expect(firstParagraph).toEqual(`Intro.`); + expect(anchor).toEqual('this-is-the-anchor'); +}); + +it('Returns the info and anchor when there are multiple paragraphs with anchors', () => { + const { firstParagraph, anchor } = extractAsciidocInfo( + `[[this-is-the-anchor]] +== Heading here + +Intro. + +[[an-anchor]] +=== Another heading + +More details + ` + ); + + expect(firstParagraph).toEqual(`Intro.`); + expect(anchor).toEqual('this-is-the-anchor'); +}); + +it('Returns the info and anchor when there are multiple paragraphs with discrete prefixes', () => { + const { firstParagraph, anchor } = extractAsciidocInfo( + `[[this-is-the-anchor]] +== Heading here + +Intro. + +[discrete] +=== Another heading + +More details + ` + ); + + expect(firstParagraph).toEqual(`Intro.`); + expect(anchor).toEqual('this-is-the-anchor'); +}); diff --git a/packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.ts b/packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.ts new file mode 100644 index 0000000000000..85b63141a2172 --- /dev/null +++ b/packages/kbn-dev-utils/src/plugin_list/extract_asciidoc_info.ts @@ -0,0 +1,32 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +export function extractAsciidocInfo(text: string): { firstParagraph?: string; anchor?: string } { + // First group is to grab the anchor - \[\[(.*)\]\] + // Tecond group, (== ), removes the equals from the header + // Third group could perhaps be done better, but is essentially: + // If there is a sub heading after the intro, match the intro and stop - (([\s\S]*?)(?=\=\=\=|\[\[))) + // If there is not a sub heading after the intro, match the intro - ([\s\S]*) + const matchAnchorAndIntro = /\[\[(.*)\]\]\n(== .*)\n(((([\s\S]*?)(?=\=\=\=|\[)))|([\s\S]*))/gm; + + const matches = matchAnchorAndIntro.exec(text); + const firstParagraph = matches && matches.length >= 4 ? matches[3].toString().trim() : undefined; + const anchor = matches && matches.length >= 2 ? matches[1].toString().trim() : undefined; + return { firstParagraph, anchor }; +} diff --git a/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts b/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts index f0f799862e24e..43dac1cb7d418 100644 --- a/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts +++ b/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts @@ -24,21 +24,29 @@ import normalizePath from 'normalize-path'; import { REPO_ROOT } from '../repo_root'; import { Plugins } from './discover_plugins'; -function* printPlugins(plugins: Plugins) { +function* printPlugins(plugins: Plugins, includes: string[]) { for (const plugin of plugins) { const path = plugin.relativeReadmePath || plugin.relativeDir; yield ''; - yield `- {kib-repo}blob/{branch}/${path}[${plugin.id}]`; + + if (plugin.readmeAsciidocAnchor) { + yield `|<<${plugin.readmeAsciidocAnchor}>>`; + + includes.push(`include::{kibana-root}/${path}[leveloffset=+1]`); + } else { + yield `|{kib-repo}blob/{branch}/${path}[${plugin.id}]`; + } if (!plugin.relativeReadmePath || plugin.readmeSnippet) { - yield ''; - yield plugin.readmeSnippet || 'WARNING: Missing README.'; + yield plugin.readmeSnippet ? `|${plugin.readmeSnippet}` : '|WARNING: Missing README.'; yield ''; } } } export function generatePluginList(ossPlugins: Plugins, xpackPlugins: Plugins) { + const includes: string[] = []; + return `//// NOTE: @@ -53,32 +61,33 @@ NOTE: //// -[[code-exploration]] -== Exploring Kibana code +[[plugin-list]] +== List of {kib} plugins -The goals of our folder heirarchy are: +[discrete] +=== src/plugins -- Easy for developers to know where to add new services, plugins and applications. -- Easy for developers to know where to find the code from services, plugins and applications. -- Easy to browse and understand our folder structure. +[%header,cols=2*] +|=== +|Name +|Description -To that aim, we strive to: +${Array.from(printPlugins(ossPlugins, includes)).join('\n')} -- Avoid too many files in any given folder. -- Choose clear, unambigious folder names. -- Organize by domain. -- Every folder should contain a README that describes the contents of that folder. +|=== [discrete] -[[kibana-services-applications]] -=== Services and Applications +=== x-pack/plugins -[discrete] -==== src/plugins -${Array.from(printPlugins(ossPlugins)).join('\n')} +[%header,cols=2*] +|=== +|Name +|Description -[discrete] -==== x-pack/plugins -${Array.from(printPlugins(xpackPlugins)).join('\n')} +${Array.from(printPlugins(xpackPlugins, includes)).join('\n')} + +|=== + +${Array.from(includes).join('\n')} `; } diff --git a/packages/kbn-dev-utils/src/plugin_list/run_plugin_list_cli.ts b/packages/kbn-dev-utils/src/plugin_list/run_plugin_list_cli.ts index 817534ba5b154..553eb1dd8afa0 100644 --- a/packages/kbn-dev-utils/src/plugin_list/run_plugin_list_cli.ts +++ b/packages/kbn-dev-utils/src/plugin_list/run_plugin_list_cli.ts @@ -28,10 +28,7 @@ import { generatePluginList } from './generate_plugin_list'; const OSS_PLUGIN_DIR = Path.resolve(REPO_ROOT, 'src/plugins'); const XPACK_PLUGIN_DIR = Path.resolve(REPO_ROOT, 'x-pack/plugins'); -const OUTPUT_PATH = Path.resolve( - REPO_ROOT, - 'docs/developer/architecture/code-exploration.asciidoc' -); +const OUTPUT_PATH = Path.resolve(REPO_ROOT, 'docs/developer/plugin-list.asciidoc'); export function runPluginListCli() { run(async ({ log }) => { diff --git a/vars/prChanges.groovy b/vars/prChanges.groovy index 5bdd62946cafc..d082672c065a8 100644 --- a/vars/prChanges.groovy +++ b/vars/prChanges.groovy @@ -22,7 +22,7 @@ def getSkippablePaths() { def getNotSkippablePaths() { return [ // this file is auto-generated and changes to it need to be validated with CI - /^docs\/developer\/architecture\/code-exploration.asciidoc$/, + /^docs\/developer\/plugin-list.asciidoc$/, // don't skip CI on prs with changes to plugin readme files (?i) is for case-insensitive matching /(?i)\/plugins\/[^\/]+\/readme\.(md|asciidoc)$/, ] diff --git a/x-pack/plugins/dashboard_enhanced/README.asciidoc b/x-pack/plugins/dashboard_enhanced/README.asciidoc new file mode 100644 index 0000000000000..2abeeb6a74e0c --- /dev/null +++ b/x-pack/plugins/dashboard_enhanced/README.asciidoc @@ -0,0 +1,5 @@ + +[[dashboard-enhanced-plugin]] +== Dashboard app enhancements plugin + +Adds drilldown capabilities to dashboard. Owned by the Kibana App team. diff --git a/x-pack/plugins/dashboard_enhanced/README.md b/x-pack/plugins/dashboard_enhanced/README.md deleted file mode 100644 index 0aeb156a99f1f..0000000000000 --- a/x-pack/plugins/dashboard_enhanced/README.md +++ /dev/null @@ -1 +0,0 @@ -Contains the enhancements to the OSS dashboard app. \ No newline at end of file diff --git a/x-pack/plugins/grokdebugger/README.md b/x-pack/plugins/grokdebugger/README.md deleted file mode 100644 index e69de29bb2d1d..0000000000000 diff --git a/x-pack/plugins/ui_actions_enhanced/README.md b/x-pack/plugins/ui_actions_enhanced/README.md index 1a72a431e3975..a4a37b559ff8d 100644 --- a/x-pack/plugins/ui_actions_enhanced/README.md +++ b/x-pack/plugins/ui_actions_enhanced/README.md @@ -1,3 +1,5 @@ # `ui_actions_enhanced` +Registers commercially licensed generic actions like per panel time range and contains some code that supports drilldown work. + - [__Dashboard drilldown user docs__](https://www.elastic.co/guide/en/kibana/master/drilldowns.html)