Remove asciidoc, switch to regex. Rearrange dev guide to avoid nestin…

…g limit.

.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'],
         ] },
       ],
     ])

docs/developer/architecture/index.asciidoc

@@ -17,12 +17,10 @@ A few notable services are called out below.
 * <<development-security>>
 * <<add-data-tutorials>>
 * <<development-visualize-index>>
-* <<code-exploration>>
 
 include::add-data-tutorials.asciidoc[leveloffset=+1]
 
 include::development-visualize-index.asciidoc[leveloffset=+1]
 
 include::security/index.asciidoc[leveloffset=+1]
 
-include::code-exploration.asciidoc[leveloffset=+1]

docs/developer/index.asciidoc

@@ -12,6 +12,7 @@ running in no time. If you have any problems, file an issue in the https://githu
 * <<external-plugin-development>>
 * <<kibana-architecture>>
 * <<advanced>>
+* <<plugin-list>>
 
 --
 
@@ -27,3 +28,5 @@ include::plugin/index.asciidoc[]
 
 include::advanced/index.asciidoc[]
 
+include::plugin-list.asciidoc[]
+

docs/developer/architecture/code-exploration.asciidoc → docs/developer/plugin-list.asciidoc

@@ -10,28 +10,11 @@ NOTE:
 
 ////
 
-[[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
+[[plugin-list]]
+== List of {kib} plugins
 
 [discrete]
-==== src/plugins
+=== src/plugins
 
 - {kib-repo}blob/{branch}/src/plugins/advanced_settings[advancedSettings]
 
@@ -60,7 +43,10 @@ WARNING: Missing README.
 
 - <<kibana-dashboard-plugin>>
 
-Registers the dashboard application.
+Dashboard plugin
+
+- 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]
@@ -278,7 +264,7 @@ WARNING: Missing README.
 
 
 [discrete]
-==== x-pack/plugins
+=== x-pack/plugins
 
 - {kib-repo}blob/{branch}/x-pack/plugins/actions/README.md[actions]
 
@@ -362,10 +348,14 @@ WARNING: Missing README.
 
 - <<enhanced-embeddables-plugin>>
 
+Enhanced embeddables plugin
+
 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

package.json

@@ -404,7 +404,6 @@
     "@typescript-eslint/parser": "^2.34.0",
     "angular-mocks": "^1.7.9",
     "archiver": "^3.1.1",
-    "asciidoctor": "^2.2.0",
     "axe-core": "^3.4.1",
     "babel-eslint": "^10.0.3",
     "babel-jest": "^25.5.1",

packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts

@@ -20,7 +20,6 @@
 import Path from 'path';
 import Fs from 'fs';
 
-import Asciidoc from 'asciidoctor';
 import MarkdownIt from 'markdown-it';
 import cheerio from 'cheerio';
 
@@ -57,17 +56,17 @@ export const discoverPlugins = (pluginsRootDir: string): Plugins =>
         const readmePath = Path.resolve(directory, readmeAsciidocName);
         relativeReadmePath = Path.relative(REPO_ROOT, readmePath);
 
-        const asciidoc = Asciidoc().loadFile(relativeReadmePath);
-
-        const parsed = asciidoc.getContent();
-        const $ = cheerio.load(parsed);
-
-        const firstParagraph = $('p')[0];
-        if (firstParagraph) {
-          readmeSnippet = $(firstParagraph).text();
-        }
-
-        readmeAsciidocAnchor = $('h2')[0].attribs.id;
+        const readmeText = Fs.readFileSync(relativeReadmePath).toString();
+        // 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(== )(((([\s\S]*?)(?=\=\=\=|\[\[)))|([\s\S]*))/gm;
+
+        const matches = matchAnchorAndIntro.exec(readmeText);
+        readmeSnippet = matches && matches.length >= 4 ? matches[3].toString() : undefined;
+        readmeAsciidocAnchor = matches && matches.length >= 2 ? matches[1].toString() : undefined;
       } else if (readmeName) {
         const readmePath = Path.resolve(directory, readmeName);
         relativeReadmePath = Path.relative(REPO_ROOT, readmePath);

packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts

@@ -62,32 +62,15 @@ NOTE:
 
 ////
 
-[[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
+[[plugin-list]]
+== List of {kib} plugins
 
 [discrete]
-==== src/plugins
+=== src/plugins
 ${Array.from(printPlugins(ossPlugins, includes)).join('\n')}
 
 [discrete]
-==== x-pack/plugins
+=== x-pack/plugins
 ${Array.from(printPlugins(xpackPlugins, includes)).join('\n')}
 
 ${Array.from(includes).join('\n')}

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 }) => {

vars/prChanges.groovy

@@ -21,7 +21,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$/,
   ]
 }
 

yarn.lock

@@ -2,21 +2,6 @@
 # yarn lockfile v1
 
 
-"@asciidoctor/cli@3.4.0":
-  version "3.4.0"
-  resolved "https://registry.yarnpkg.com/@asciidoctor/cli/-/cli-3.4.0.tgz#586e9133f3367c7b3236631197f4b621890d9227"
-  integrity sha512-jOtxA0I6zB+6z+GGwm9+xhlmGTqCTkFPE902L6fauFlE6v7LxjhLYNxvjDVyn0zMrFLybvoSRcAnM3DcticNoQ==
-  dependencies:
-    yargs "15.3.1"
-
-"@asciidoctor/core@2.2.0":
-  version "2.2.0"
-  resolved "https://registry.yarnpkg.com/@asciidoctor/core/-/core-2.2.0.tgz#cae722e32666bf3c38365afe7d05f2f433b165fd"
-  integrity sha512-WN/mFuU4SeWaDqpGvRwAf+Tq2T8NQkVVpZ3Ne1/ZRxDKElzFkqq8bGbmxSMWmMVzC+H9ZO1YxxbOjhWEiNvpOA==
-  dependencies:
-    asciidoctor-opal-runtime "0.3.0"
-    unxhr "1.0.1"
-
 "@babel/cli@^7.10.1":
   version "7.10.1"
   resolved "https://registry.yarnpkg.com/@babel/cli/-/cli-7.10.1.tgz#b6e5cd43a17b8f639442ab027976408ebe6d79a0"
@@ -7246,22 +7231,6 @@ asap@^2.0.0, asap@~2.0.3:
   resolved "https://registry.yarnpkg.com/asap/-/asap-2.0.6.tgz#e50347611d7e690943208bbdafebcbc2fb866d46"
   integrity sha1-5QNHYR1+aQlDIIu9r+vLwvuGbUY=
 
-asciidoctor-opal-runtime@0.3.0:
-  version "0.3.0"
-  resolved "https://registry.yarnpkg.com/asciidoctor-opal-runtime/-/asciidoctor-opal-runtime-0.3.0.tgz#df327a870ddd3cd5eb0e162d64ed4dcdd3fe3fee"
-  integrity sha512-YapVwl2qbbs6sIe1dvAlMpBzQksFVTSa2HOduOKFNhZlE9bNmn+moDgGVvjWPbzMPo/g8gItyTHfWB2u7bQxag==
-  dependencies:
-    glob "7.1.3"
-    unxhr "1.0.1"
-
-asciidoctor@^2.2.0:
-  version "2.2.0"
-  resolved "https://registry.yarnpkg.com/asciidoctor/-/asciidoctor-2.2.0.tgz#880f0dfe349d7dcc8b819ebc691bf1fd36d47bbe"
-  integrity sha512-w5oBMYPaA5RP/Qlv6XQzWE7kSf8d9sLMRBItcU+nn7E/FF9yGLUd1p/dzqWiu600KyNHBpp8Ml/VTaGjUm6LrQ==
-  dependencies:
-    "@asciidoctor/cli" "3.4.0"
-    "@asciidoctor/core" "2.2.0"
-
 asn1.js@^4.0.0:
   version "4.10.1"
   resolved "https://registry.yarnpkg.com/asn1.js/-/asn1.js-4.10.1.tgz#b9c2bf5805f1e64aadeed6df3a2bfafb5a73f5a0"
@@ -30511,11 +30480,6 @@ untildify@^3.0.3:
   resolved "https://registry.yarnpkg.com/untildify/-/untildify-3.0.3.tgz#1e7b42b140bcfd922b22e70ca1265bfe3634c7c9"
   integrity sha512-iSk/J8efr8uPT/Z4eSUywnqyrQU7DSdMfdqK4iWEaUVVmcP5JcnpRqmVMwcwcnmI1ATFNgC5V90u09tBynNFKA==
 
-unxhr@1.0.1:
-  version "1.0.1"
-  resolved "https://registry.yarnpkg.com/unxhr/-/unxhr-1.0.1.tgz#92200322d66c728993de771f9e01eeb21f41bc7b"
-  integrity sha512-MAhukhVHyaLGDjyDYhy8gVjWJyhTECCdNsLwlMoGFoNJ3o79fpQhtQuzmAE4IxCMDwraF4cW8ZjpAV0m9CRQbg==
-
 unzip-response@^1.0.0:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/unzip-response/-/unzip-response-1.0.2.tgz#b984f0877fc0a89c2c773cc1ef7b5b232b5b06fe"
@@ -32478,23 +32442,6 @@ yargs@13.3.2, yargs@^13.2.2, yargs@^13.3.0:
     y18n "^4.0.0"
     yargs-parser "^13.1.2"
 
-yargs@15.3.1, yargs@^15.0.2, yargs@^15.1.0, yargs@^15.3.1, yargs@~15.3.1:
-  version "15.3.1"
-  resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.3.1.tgz#9505b472763963e54afe60148ad27a330818e98b"
-  integrity sha512-92O1HWEjw27sBfgmXiixJWT5hRBp2eobqXicLtPBIDBhYB+1HpwZlXmbW2luivBJHBzki+7VyCLRtAkScbTBQA==
-  dependencies:
-    cliui "^6.0.0"
-    decamelize "^1.2.0"
-    find-up "^4.1.0"
-    get-caller-file "^2.0.1"
-    require-directory "^2.1.1"
-    require-main-filename "^2.0.0"
-    set-blocking "^2.0.0"
-    string-width "^4.2.0"
-    which-module "^2.0.0"
-    y18n "^4.0.0"
-    yargs-parser "^18.1.1"
-
 yargs@4.8.1:
   version "4.8.1"
   resolved "https://registry.yarnpkg.com/yargs/-/yargs-4.8.1.tgz#c0c42924ca4aaa6b0e6da1739dfb216439f9ddc0"
@@ -32515,6 +32462,23 @@ yargs@4.8.1:
     y18n "^3.2.1"
     yargs-parser "^2.4.1"
 
+yargs@^15.0.2, yargs@^15.1.0, yargs@^15.3.1, yargs@~15.3.1:
+  version "15.3.1"
+  resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.3.1.tgz#9505b472763963e54afe60148ad27a330818e98b"
+  integrity sha512-92O1HWEjw27sBfgmXiixJWT5hRBp2eobqXicLtPBIDBhYB+1HpwZlXmbW2luivBJHBzki+7VyCLRtAkScbTBQA==
+  dependencies:
+    cliui "^6.0.0"
+    decamelize "^1.2.0"
+    find-up "^4.1.0"
+    get-caller-file "^2.0.1"
+    require-directory "^2.1.1"
+    require-main-filename "^2.0.0"
+    set-blocking "^2.0.0"
+    string-width "^4.2.0"
+    which-module "^2.0.0"
+    y18n "^4.0.0"
+    yargs-parser "^18.1.1"
+
 yargs@^15.4.0:
   version "15.4.1"
   resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.4.1.tgz#0d87a16de01aee9d8bec2bfbf74f67851730f4f8"