[ML] Update API docs generation script to comply with new docs format (…

…#109343) (#109781) * [ML] update deps * [ML] fix script * [ML] add header * [ML] generate header Co-authored-by: Dima Arnautov <[email protected]>
elastic · Aug 24, 2021 · f57fa6d · f57fa6d
1 parent e4fa7e4
commit f57fa6d
Show file tree

Hide file tree

Showing 9 changed files with 157 additions and 40 deletions.
diff --git a/package.json b/package.json
@@ -502,6 +502,7 @@
     "@testing-library/user-event": "^13.1.1",
     "@types/angular": "^1.6.56",
     "@types/angular-mocks": "^1.7.0",
+    "@types/apidoc": "^0.22.3",
     "@types/archiver": "^5.1.0",
     "@types/babel__core": "^7.1.12",
     "@types/base64-js": "^1.2.5",
@@ -659,8 +660,8 @@
     "aggregate-error": "^3.1.0",
     "angular-mocks": "^1.7.9",
     "antlr4ts-cli": "^0.5.0-alpha.3",
-    "apidoc": "^0.25.0",
-    "apidoc-markdown": "^5.1.8",
+    "apidoc": "^0.29.0",
+    "apidoc-markdown": "^6.0.0",
     "argsplit": "^1.0.5",
     "autoprefixer": "^9.7.4",
     "axe-core": "^4.0.2",

diff --git a/x-pack/plugins/ml/package.json b/x-pack/plugins/ml/package.json
@@ -6,6 +6,7 @@
   "license": "Elastic-License",
   "scripts": {
     "build:apiDocScripts": "cd server/routes/apidoc_scripts && ../../../../../../node_modules/.bin/tsc",
-    "apiDocs": "yarn build:apiDocScripts && cd ./server/routes/ && ../../../../../node_modules/.bin/apidoc --parse-workers apischema=./apidoc_scripts/target/schema_worker.js --parse-parsers apischema=./apidoc_scripts/target/schema_parser.js --parse-filters apiversion=./apidoc_scripts/target/version_filter.js  -i . -o ../routes_doc && ../../../../../node_modules/.bin/apidoc-markdown -p ../routes_doc -o ../routes_doc/ML_API.md -t ./apidoc_scripts/template.md"
+    "generateHeader": "node server/routes/apidoc_scripts/target/header_generator.js",
+    "apiDocs": "yarn build:apiDocScripts && yarn generateHeader && cd ./server/routes/ && ../../../../../node_modules/.bin/apidoc --parse-workers apischema=./apidoc_scripts/target/schema_worker.js --parse-parsers apischema=./apidoc_scripts/target/schema_parser.js --parse-filters apiversion=./apidoc_scripts/target/version_filter.js -i . -o ../routes_doc && ../../../../../node_modules/.bin/apidoc-markdown -p ../routes_doc -o ../routes_doc/ML_API.mdx --header ./apidoc_scripts/header.md --template ./apidoc_scripts/template.md"
   }
 }
diff --git a/x-pack/plugins/ml/server/routes/apidoc.json b/x-pack/plugins/ml/server/routes/apidoc.json
@@ -1,6 +1,6 @@
 {
   "name": "ml_kibana_api",
-  "version": "7.13.0",
+  "version": "7.15.0",
   "description": "This is the documentation of the REST API provided by the Machine Learning Kibana plugin. Each API is experimental and can include breaking changes in any version.",
   "title": "ML Kibana API",
   "order": [

diff --git a/x-pack/plugins/ml/server/routes/apidoc_scripts/header_generator.ts b/x-pack/plugins/ml/server/routes/apidoc_scripts/header_generator.ts
@@ -0,0 +1,21 @@
+/*
+ * 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; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import moment from 'moment';
+
+const getHeaderString = () => `---
+id: uiMlApi
+slug: /ml-team/docs/ui/rest-api/ml-api
+title: ML API reference
+description: Reference documentation for the ML API.
+date: ${moment().format('YYYY-MM-DD')}
+tags: ['machine learning','internal docs', 'UI']
+---`;
+
+fs.writeFileSync(path.resolve(__dirname, '..', 'header.md'), getHeaderString());
diff --git a/x-pack/plugins/ml/server/routes/apidoc_scripts/schema_worker.ts b/x-pack/plugins/ml/server/routes/apidoc_scripts/schema_worker.ts
@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { DocEntry, extractDocumentation } from './schema_extractor';
-import { ApiParameter, Block } from './types';
+import type { ApiParameter, Block } from './types';
 
 export function postProcess(parsedFiles: any[]): void {
   const schemasDirPath = path.resolve(__dirname, '..', '..', 'schemas');
@@ -19,6 +19,7 @@ export function postProcess(parsedFiles: any[]): void {
   const schemaDocs = extractDocumentation(schemaFiles);
 
   parsedFiles.forEach((parsedFile) => {
+    // @ts-ignore
     parsedFile.forEach((block: Block) => {
       const {
         local: { schemas },

diff --git a/x-pack/plugins/ml/server/routes/apidoc_scripts/template.md b/x-pack/plugins/ml/server/routes/apidoc_scripts/template.md
@@ -1,3 +1,7 @@
+<% if (header) { -%>
+<%- header %>
+<% } -%>
+
 <a name="top"></a>
 # <%= project.name %> v<%= project.version %>
 

diff --git a/x-pack/plugins/ml/server/routes/apidoc_scripts/tsconfig.json b/x-pack/plugins/ml/server/routes/apidoc_scripts/tsconfig.json
@@ -1,12 +1,14 @@
 {
   "extends": "../../../../../../tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "./target/types"
+    "outDir": "./target"
   },
   "include": [
     "schema_worker.ts",
     "schema_parser.ts",
     "schema_extractor.ts",
-    "version_filter.ts"
+    "version_filter.ts",
+    "types.ts",
+    "header_generator.ts"
   ]
 }
diff --git a/x-pack/plugins/ml/server/routes/apidoc_scripts/version_filter.ts b/x-pack/plugins/ml/server/routes/apidoc_scripts/version_filter.ts
@@ -7,7 +7,7 @@
 
 import { Block } from './types';
 
-const API_VERSION = '7.13.0';
+const API_VERSION = '7.15.0';
 
 /**
  * Post Filter parsed results.