Co-authored-by: Stacey Gammon <gammon@elastic.co>
This commit is contained in:
parent
f6e6149e66
commit
7535f23a55
13 changed files with 1710 additions and 19 deletions
|
@ -50,7 +50,6 @@ export function buildApiDeclaration(
|
|||
name?: string
|
||||
): ApiDeclaration {
|
||||
const apiName = name ? name : isNamedNode(node) ? node.getName() : 'Unnamed';
|
||||
log.debug(`Building API Declaration for ${apiName} of kind ${node.getKindName()}`);
|
||||
const apiId = parentApiId ? parentApiId + '.' + apiName : apiName;
|
||||
const anchorLink: AnchorLink = { scope, pluginName, apiName: apiId };
|
||||
|
||||
|
|
|
@ -47,9 +47,6 @@ export function getArrowFunctionDec(
|
|||
anchorLink: AnchorLink,
|
||||
log: ToolingLog
|
||||
) {
|
||||
log.debug(
|
||||
`Getting Arrow Function doc def for node ${node.getName()} of kind ${node.getKindName()}`
|
||||
);
|
||||
return {
|
||||
id: getApiSectionId(anchorLink),
|
||||
type: TypeKind.FunctionKind,
|
||||
|
|
|
@ -39,7 +39,6 @@ export function buildFunctionDec(
|
|||
const label = Node.isConstructorDeclaration(node)
|
||||
? 'Constructor'
|
||||
: node.getName() || '(WARN: Missing name)';
|
||||
log.debug(`Getting function doc def for node ${label} of kind ${node.getKindName()}`);
|
||||
return {
|
||||
id: getApiSectionId(anchorLink),
|
||||
type: TypeKind.FunctionKind,
|
||||
|
|
|
@ -45,7 +45,6 @@ export function buildVariableDec(
|
|||
anchorLink: AnchorLink,
|
||||
log: ToolingLog
|
||||
): ApiDeclaration {
|
||||
log.debug('buildVariableDec for ' + node.getName());
|
||||
const initializer = node.getInitializer();
|
||||
// Recusively list object properties as children.
|
||||
if (initializer && Node.isObjectLiteralExpression(initializer)) {
|
||||
|
|
|
@ -6,6 +6,7 @@
|
|||
* Side Public License, v 1.
|
||||
*/
|
||||
|
||||
import { REPO_ROOT } from '@kbn/utils';
|
||||
import { KibanaPlatformPlugin, ToolingLog } from '@kbn/dev-utils';
|
||||
import { getPluginApiDocId } from '../utils';
|
||||
import { extractImportReferences } from './extract_import_refs';
|
||||
|
@ -82,7 +83,43 @@ it('test extractImportReference with unknown imports', () => {
|
|||
expect(results.length).toBe(3);
|
||||
expect(results[0]).toBe('<I extends ');
|
||||
expect(results[1]).toBe('FooFoo');
|
||||
expect(results[2]).toBe('>');
|
||||
});
|
||||
|
||||
it('test full file imports with no matching plugin', () => {
|
||||
const refs = extractImportReferences(
|
||||
`typeof import("${REPO_ROOT}/src/plugins/data/common/es_query/kuery/node_types/function")`,
|
||||
plugins,
|
||||
log
|
||||
);
|
||||
expect(refs).toMatchInlineSnapshot(`
|
||||
Array [
|
||||
"typeof ",
|
||||
"src/plugins/data/common/es_query/kuery/node_types/function",
|
||||
]
|
||||
`);
|
||||
expect(refs.length).toBe(2);
|
||||
});
|
||||
|
||||
it('test full file imports with a matching plugin', () => {
|
||||
const refs = extractImportReferences(
|
||||
`typeof import("${plugin.directory}/public/foo/index") something`,
|
||||
plugins,
|
||||
log
|
||||
);
|
||||
expect(refs).toMatchInlineSnapshot(`
|
||||
Array [
|
||||
"typeof ",
|
||||
Object {
|
||||
"docId": "kibPluginAPluginApi",
|
||||
"pluginId": "pluginA",
|
||||
"scope": "public",
|
||||
"section": undefined,
|
||||
"text": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index",
|
||||
},
|
||||
" something",
|
||||
]
|
||||
`);
|
||||
expect(refs.length).toBe(3);
|
||||
});
|
||||
|
||||
it('test single link', () => {
|
||||
|
|
|
@ -9,6 +9,7 @@
|
|||
import { KibanaPlatformPlugin, ToolingLog } from '@kbn/dev-utils';
|
||||
import { getApiSectionId, getPluginApiDocId, getPluginForPath } from '../utils';
|
||||
import { ApiScope, TextWithLinks } from '../types';
|
||||
import { getRelativePath } from './utils';
|
||||
|
||||
/**
|
||||
*
|
||||
|
@ -54,6 +55,9 @@ export function extractImportReferences(
|
|||
const str = textSegment.substr(index + length - name.length, name.length);
|
||||
if (str && str !== '') {
|
||||
texts.push(str);
|
||||
} else {
|
||||
// If there is no ".Name" then use the full path. You can see things like "typeof import("file")"
|
||||
texts.push(getRelativePath(path));
|
||||
}
|
||||
} else {
|
||||
const section = getApiSectionId({
|
||||
|
@ -69,10 +73,12 @@ export function extractImportReferences(
|
|||
apiPath: path,
|
||||
directory: plugin.directory,
|
||||
}),
|
||||
section,
|
||||
text: name,
|
||||
section: name && name !== '' ? section : undefined,
|
||||
text: name && name !== '' ? name : getRelativePath(path),
|
||||
});
|
||||
}
|
||||
|
||||
// Prep textSegment to skip past the `import`, then check for more.
|
||||
textSegment = textSegment.substr(index + length);
|
||||
} else {
|
||||
if (textSegment && textSegment !== '') {
|
||||
|
@ -87,10 +93,10 @@ export function extractImportReferences(
|
|||
function extractImportRef(
|
||||
str: string
|
||||
): { path: string; name: string; index: number; length: number } | undefined {
|
||||
const groups = str.match(/import\("(.*?)"\)\.(\w*)/);
|
||||
const groups = str.match(/import\("(.*?)"\)\.?(\w*)/);
|
||||
if (groups) {
|
||||
const path = groups[1];
|
||||
const name = groups[2];
|
||||
const name = groups.length > 2 ? groups[2] : '';
|
||||
const index = groups.index!;
|
||||
const length = groups[0].length;
|
||||
return { path, name, index, length };
|
||||
|
|
|
@ -17,7 +17,7 @@ export function isPrivate(node: ParameterDeclaration | ClassMemberTypes): boolea
|
|||
/**
|
||||
* Change the absolute path into a relative one.
|
||||
*/
|
||||
function getRelativePath(fullPath: string): string {
|
||||
export function getRelativePath(fullPath: string): string {
|
||||
return Path.relative(REPO_ROOT, fullPath);
|
||||
}
|
||||
|
||||
|
|
|
@ -84,7 +84,7 @@ import ${json} from './${fileName}.json';
|
|||
common: groupPluginApi(doc.common),
|
||||
server: groupPluginApi(doc.server),
|
||||
};
|
||||
fs.writeFileSync(Path.resolve(folder, fileName + '.json'), JSON.stringify(scopedDoc));
|
||||
fs.writeFileSync(Path.resolve(folder, fileName + '.json'), JSON.stringify(scopedDoc, null, 2));
|
||||
|
||||
mdx += scopApiToMdx(scopedDoc.client, 'Client', json, 'client');
|
||||
mdx += scopApiToMdx(scopedDoc.server, 'Server', json, 'server');
|
||||
|
|
File diff suppressed because one or more lines are too long
|
@ -1 +1,77 @@
|
|||
{"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":[]}}
|
||||
{
|
||||
"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/masterpackages/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/masterpackages/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/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts#L9"
|
||||
},
|
||||
"signature": [
|
||||
"\"COMMON VAR!\""
|
||||
],
|
||||
"initialIsOpen": false
|
||||
}
|
||||
],
|
||||
"objects": []
|
||||
}
|
||||
}
|
|
@ -97,7 +97,7 @@ export interface Reference {
|
|||
pluginId: string;
|
||||
scope: ApiScope;
|
||||
docId: string;
|
||||
section: string;
|
||||
section?: string;
|
||||
text: string;
|
||||
}
|
||||
|
||||
|
|
|
@ -91,9 +91,6 @@ export function getPluginApiDocId(
|
|||
const cleanName = id.replace('.', '_');
|
||||
if (serviceInfo) {
|
||||
const serviceName = getServiceForPath(serviceInfo.apiPath, serviceInfo.directory);
|
||||
log.debug(
|
||||
`Service for path ${serviceInfo.apiPath} and ${serviceInfo.directory} is ${serviceName}`
|
||||
);
|
||||
const serviceFolder = serviceInfo.serviceFolders?.find((f) => f === serviceName);
|
||||
|
||||
if (serviceFolder) {
|
||||
|
|
|
@ -87,3 +87,19 @@ if [ "$GIT_CHANGES" ]; then
|
|||
echo -e "$GIT_CHANGES\n"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
###
|
||||
### rebuild plugin api docs to ensure it's not out of date
|
||||
###
|
||||
echo " -- building api docs"
|
||||
node scripts/build_api_docs
|
||||
|
||||
###
|
||||
### verify no api changes
|
||||
###
|
||||
GIT_CHANGES="$(git ls-files --modified)"
|
||||
if [ "$GIT_CHANGES" ]; then
|
||||
echo -e "\n${RED}ERROR: 'node scripts/build_api_docs' caused changes to the following files:${C_RESET}\n"
|
||||
echo -e "$GIT_CHANGES\n"
|
||||
exit 1
|
||||
fi
|
Loading…
Reference in a new issue