Skip to content

Commit b9cafa0

Browse files
author
Stacey Gammon
committed
API docs
1 parent f0f7fea commit b9cafa0

13 files changed

Lines changed: 1710 additions & 19 deletions

File tree

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_api_declaration.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,6 @@ export function buildApiDeclaration(
5050
name?: string
5151
): ApiDeclaration {
5252
const apiName = name ? name : isNamedNode(node) ? node.getName() : 'Unnamed';
53-
log.debug(`Building API Declaration for ${apiName} of kind ${node.getKindName()}`);
5453
const apiId = parentApiId ? parentApiId + '.' + apiName : apiName;
5554
const anchorLink: AnchorLink = { scope, pluginName, apiName: apiId };
5655

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_arrow_fn_dec.ts‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,6 @@ export function getArrowFunctionDec(
4747
anchorLink: AnchorLink,
4848
log: ToolingLog
4949
) {
50-
log.debug(
51-
`Getting Arrow Function doc def for node ${node.getName()} of kind ${node.getKindName()}`
52-
);
5350
return {
5451
id: getApiSectionId(anchorLink),
5552
type: TypeKind.FunctionKind,

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_function_dec.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,6 @@ export function buildFunctionDec(
3939
const label = Node.isConstructorDeclaration(node)
4040
? 'Constructor'
4141
: node.getName() || '(WARN: Missing name)';
42-
log.debug(`Getting function doc def for node ${label} of kind ${node.getKindName()}`);
4342
return {
4443
id: getApiSectionId(anchorLink),
4544
type: TypeKind.FunctionKind,

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_variable_dec.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,6 @@ export function buildVariableDec(
4545
anchorLink: AnchorLink,
4646
log: ToolingLog
4747
): ApiDeclaration {
48-
log.debug('buildVariableDec for ' + node.getName());
4948
const initializer = node.getInitializer();
5049
// Recusively list object properties as children.
5150
if (initializer && Node.isObjectLiteralExpression(initializer)) {

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/extract_import_refs.test.ts‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* Side Public License, v 1.
77
*/
88

9+
import { REPO_ROOT } from '@kbn/utils';
910
import { KibanaPlatformPlugin, ToolingLog } from '@kbn/dev-utils';
1011
import { getPluginApiDocId } from '../utils';
1112
import { extractImportReferences } from './extract_import_refs';
@@ -82,7 +83,43 @@ it('test extractImportReference with unknown imports', () => {
8283
expect(results.length).toBe(3);
8384
expect(results[0]).toBe('<I extends ');
8485
expect(results[1]).toBe('FooFoo');
85-
expect(results[2]).toBe('>');
86+
});
87+
88+
it('test full file imports with no matching plugin', () => {
89+
const refs = extractImportReferences(
90+
`typeof import("${REPO_ROOT}/src/plugins/data/common/es_query/kuery/node_types/function")`,
91+
plugins,
92+
log
93+
);
94+
expect(refs).toMatchInlineSnapshot(`
95+
Array [
96+
"typeof ",
97+
"src/plugins/data/common/es_query/kuery/node_types/function",
98+
]
99+
`);
100+
expect(refs.length).toBe(2);
101+
});
102+
103+
it('test full file imports with a matching plugin', () => {
104+
const refs = extractImportReferences(
105+
`typeof import("${plugin.directory}/public/foo/index") something`,
106+
plugins,
107+
log
108+
);
109+
expect(refs).toMatchInlineSnapshot(`
110+
Array [
111+
"typeof ",
112+
Object {
113+
"docId": "kibPluginAPluginApi",
114+
"pluginId": "pluginA",
115+
"scope": "public",
116+
"section": undefined,
117+
"text": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index",
118+
},
119+
" something",
120+
]
121+
`);
122+
expect(refs.length).toBe(3);
86123
});
87124

88125
it('test single link', () => {

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/extract_import_refs.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import { KibanaPlatformPlugin, ToolingLog } from '@kbn/dev-utils';
1010
import { getApiSectionId, getPluginApiDocId, getPluginForPath } from '../utils';
1111
import { ApiScope, TextWithLinks } from '../types';
12+
import { getRelativePath } from './utils';
1213

1314
/**
1415
*
@@ -54,6 +55,9 @@ export function extractImportReferences(
5455
const str = textSegment.substr(index + length - name.length, name.length);
5556
if (str && str !== '') {
5657
texts.push(str);
58+
} else {
59+
// If there is no ".Name" then use the full path. You can see things like "typeof import("file")"
60+
texts.push(getRelativePath(path));
5761
}
5862
} else {
5963
const section = getApiSectionId({
@@ -69,10 +73,12 @@ export function extractImportReferences(
6973
apiPath: path,
7074
directory: plugin.directory,
7175
}),
72-
section,
73-
text: name,
76+
section: name && name !== '' ? section : undefined,
77+
text: name && name !== '' ? name : getRelativePath(path),
7478
});
7579
}
80+
81+
// Prep textSegment to skip past the `import`, then check for more.
7682
textSegment = textSegment.substr(index + length);
7783
} else {
7884
if (textSegment && textSegment !== '') {
@@ -87,10 +93,10 @@ export function extractImportReferences(
8793
function extractImportRef(
8894
str: string
8995
): { path: string; name: string; index: number; length: number } | undefined {
90-
const groups = str.match(/import\("(.*?)"\)\.(\w*)/);
96+
const groups = str.match(/import\("(.*?)"\)\.?(\w*)/);
9197
if (groups) {
9298
const path = groups[1];
93-
const name = groups[2];
99+
const name = groups.length > 2 ? groups[2] : '';
94100
const index = groups.index!;
95101
const length = groups[0].length;
96102
return { path, name, index, length };

‎packages/kbn-docs-utils/src/api_docs/build_api_declarations/utils.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ export function isPrivate(node: ParameterDeclaration | ClassMemberTypes): boolea
1717
/**
1818
* Change the absolute path into a relative one.
1919
*/
20-
function getRelativePath(fullPath: string): string {
20+
export function getRelativePath(fullPath: string): string {
2121
return Path.relative(REPO_ROOT, fullPath);
2222
}
2323

‎packages/kbn-docs-utils/src/api_docs/mdx/write_plugin_mdx_docs.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ import ${json} from './${fileName}.json';
8484
common: groupPluginApi(doc.common),
8585
server: groupPluginApi(doc.server),
8686
};
87-
fs.writeFileSync(Path.resolve(folder, fileName + '.json'), JSON.stringify(scopedDoc));
87+
fs.writeFileSync(Path.resolve(folder, fileName + '.json'), JSON.stringify(scopedDoc, null, 2));
8888

8989
mdx += scopApiToMdx(scopedDoc.client, 'Client', json, 'client');
9090
mdx += scopApiToMdx(scopedDoc.server, 'Server', json, 'server');

‎packages/kbn-docs-utils/src/api_docs/tests/snapshots/plugin_a.json‎

Lines changed: 1566 additions & 1 deletion
Large diffs are not rendered by default.

‎packages/kbn-docs-utils/src/api_docs/tests/snapshots/plugin_a_foo.json‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,77 @@
1-
{"id":"pluginA.foo","client":{"classes":[],"functions":[{"id":"def-public.doTheFooFnThing","type":"Function","children":[],"signature":["() => void"],"description":[],"label":"doTheFooFnThing","source":{"path":"/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts","lineNumber":9,"link":"https://github.com/elastic/kibana/tree/master/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L9"},"returnComment":[],"initialIsOpen":false}],"interfaces":[],"enums":[],"misc":[{"id":"def-public.FooType","type":"Type","label":"FooType","description":[],"source":{"path":"/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts","lineNumber":11,"link":"https://github.com/elastic/kibana/tree/master/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L11"},"signature":["() => \"foo\""],"initialIsOpen":false}],"objects":[]},"server":{"classes":[],"functions":[],"interfaces":[],"enums":[],"misc":[],"objects":[]},"common":{"classes":[],"functions":[],"interfaces":[],"enums":[],"misc":[{"id":"def-common.commonFoo","type":"string","label":"commonFoo","description":[],"source":{"path":"/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts","lineNumber":9,"link":"https://github.com/elastic/kibana/tree/master/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts#L9"},"signature":["\"COMMON VAR!\""],"initialIsOpen":false}],"objects":[]}}
1+
{
2+
"id": "pluginA.foo",
3+
"client": {
4+
"classes": [],
5+
"functions": [
6+
{
7+
"id": "def-public.doTheFooFnThing",
8+
"type": "Function",
9+
"children": [],
10+
"signature": [
11+
"() => void"
12+
],
13+
"description": [],
14+
"label": "doTheFooFnThing",
15+
"source": {
16+
"path": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts",
17+
"lineNumber": 9,
18+
"link": "https://github.com/elastic/kibana/tree/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L9"
19+
},
20+
"returnComment": [],
21+
"initialIsOpen": false
22+
}
23+
],
24+
"interfaces": [],
25+
"enums": [],
26+
"misc": [
27+
{
28+
"id": "def-public.FooType",
29+
"type": "Type",
30+
"label": "FooType",
31+
"description": [],
32+
"source": {
33+
"path": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts",
34+
"lineNumber": 11,
35+
"link": "https://github.com/elastic/kibana/tree/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L11"
36+
},
37+
"signature": [
38+
"() => \"foo\""
39+
],
40+
"initialIsOpen": false
41+
}
42+
],
43+
"objects": []
44+
},
45+
"server": {
46+
"classes": [],
47+
"functions": [],
48+
"interfaces": [],
49+
"enums": [],
50+
"misc": [],
51+
"objects": []
52+
},
53+
"common": {
54+
"classes": [],
55+
"functions": [],
56+
"interfaces": [],
57+
"enums": [],
58+
"misc": [
59+
{
60+
"id": "def-common.commonFoo",
61+
"type": "string",
62+
"label": "commonFoo",
63+
"description": [],
64+
"source": {
65+
"path": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts",
66+
"lineNumber": 9,
67+
"link": "https://github.com/elastic/kibana/tree/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts#L9"
68+
},
69+
"signature": [
70+
"\"COMMON VAR!\""
71+
],
72+
"initialIsOpen": false
73+
}
74+
],
75+
"objects": []
76+
}
77+
}

0 commit comments

Comments
 (0)