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

docs/developer/architecture/code-exploration.asciidoc

@@ -58,9 +58,9 @@ The Charts plugin is a way to create easier integration of shared colors, themes
 WARNING: Missing README.
 
 
-- {kib-repo}blob/{branch}/src/plugins/dashboard[dashboard]
+- <<kibana-dashboard-plugin>>
 
-WARNING: Missing README.
+Registers the dashboard application.
 
 
 - {kib-repo}blob/{branch}/src/plugins/data/README.md[data]
@@ -360,9 +360,10 @@ WARNING: Missing README.
 WARNING: Missing README.
 
 
-- {kib-repo}blob/{branch}/x-pack/plugins/embeddable_enhanced[embeddableEnhanced]
+- <<enhanced-embeddables-plugin>>
 
-WARNING: Missing README.
+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]
@@ -582,3 +583,6 @@ in their infrastructure.
 
 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/embeddable_enhanced/README.asciidoc[leveloffset=+1]

package.json

@@ -404,6 +404,7 @@
  "@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,6 +20,7 @@
 import Path from 'path';
 import Fs from 'fs';
 
+import Asciidoc from 'asciidoctor';
 import MarkdownIt from 'markdown-it';
 import cheerio from 'cheerio';
 
@@ -31,21 +32,43 @@ export interface Plugin {
  relativeDir?: string;
  relativeReadmePath?: string;
  readmeSnippet?: string;
+ readmeAsciidocAnchor?: string;
 }
 
 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 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;
+ } else if (readmeName) {
  const readmePath = Path.resolve(directory, readmeName);
  relativeReadmePath = Path.relative(REPO_ROOT, readmePath);
 
@@ -64,6 +87,7 @@ export const discoverPlugins = (pluginsRootDir: string): Plugins =>
  relativeReadmePath,
  relativeDir: relativeReadmePath || Path.relative(REPO_ROOT, directory),
  readmeSnippet,
+ readmeAsciidocAnchor,
  };
  }
  );

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

@@ -24,11 +24,18 @@ 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 '';
@@ -39,6 +46,8 @@ function* printPlugins(plugins: Plugins) {
 }
 
 export function generatePluginList(ossPlugins: Plugins, xpackPlugins: Plugins) {
+ const includes: string[] = [];
+
  return `////
 
 NOTE:
@@ -75,10 +84,12 @@ To that aim, we strive to:
 
 [discrete]
 ==== src/plugins
-${Array.from(printPlugins(ossPlugins)).join('\n')}
+${Array.from(printPlugins(ossPlugins, includes)).join('\n')}
 
 [discrete]
 ==== x-pack/plugins
-${Array.from(printPlugins(xpackPlugins)).join('\n')}
+${Array.from(printPlugins(xpackPlugins, includes)).join('\n')}
+
+${Array.from(includes).join('\n')}
 `;
 }

yarn.lock

@@ -2,6 +2,21 @@
 # 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"
@@ -7634,6 +7649,22 @@ 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"
@@ -31435,6 +31466,11 @@ 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"
@@ -33372,6 +33408,23 @@ 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"
@@ -33392,23 +33445,6 @@ 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"