From acc37d9ee9dc680c84e3b0ca3a1cdf10fce4edfd Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Fri, 31 Jul 2020 09:44:32 -0400 Subject: [PATCH] Remove asciidoc, switch to regex. Rearrange dev guide to avoid nesting limit. --- .../src/test/prChanges.groovy | 2 +- docs/developer/architecture/index.asciidoc | 2 - docs/developer/index.asciidoc | 3 + ...loration.asciidoc => plugin-list.asciidoc} | 34 ++++----- package.json | 1 - .../src/plugin_list/discover_plugins.ts | 23 +++--- .../src/plugin_list/generate_plugin_list.ts | 25 ++----- .../src/plugin_list/run_plugin_list_cli.ts | 5 +- vars/prChanges.groovy | 2 +- yarn.lock | 70 +++++-------------- 10 files changed, 50 insertions(+), 117 deletions(-) rename docs/developer/{architecture/code-exploration.asciidoc => plugin-list.asciidoc} (96%) diff --git a/.ci/pipeline-library/src/test/prChanges.groovy b/.ci/pipeline-library/src/test/prChanges.groovy index f149340517ff0..6ad3eab7549dd 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/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/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/architecture/code-exploration.asciidoc b/docs/developer/plugin-list.asciidoc similarity index 96% rename from docs/developer/architecture/code-exploration.asciidoc rename to docs/developer/plugin-list.asciidoc index 7ca206835ec10..d5d276139804d 100644 --- a/docs/developer/architecture/code-exploration.asciidoc +++ b/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. - <> -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 + 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 diff --git a/package.json b/package.json index 37ca8d02d2318..880534997cff0 100644 --- a/package.json +++ b/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", 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 801c1b9db2e47..caac58dee23ca 100644 --- a/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts +++ b/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); 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 1bd568a4df807..c2da9949e84c7 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 @@ -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')} 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 adaacf952b5b6..c1522a22fa3d8 100644 --- a/vars/prChanges.groovy +++ b/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$/, ] } diff --git a/yarn.lock b/yarn.lock index 08bdeebd5c75b..a70f04e030447 100644 --- a/yarn.lock +++ b/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"