Skip to content

Commit c5b26d0

Browse files
vasilev-alexvasilev-alex
authored
fix(docs-gen): generator fixes, docs updates
1 parent ff3fe29 commit c5b26d0

File tree

17 files changed

+299
-571
lines changed

17 files changed

+299
-571
lines changed

‎docs-gen/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
],
99
"scripts": {
1010
"lint": "tslint --project ./tsconfig.json",
11-
"generate": "yarn build && typedoc --excludeExternals --includeDeclarations --plugin ../docs-gen/dist/index.js --hideSources --hideIndexes --out ../docs/Cube.js-Frontend --name @cubejs-client-core ../packages/cubejs-client-core/index.d.ts",
11+
"generate": "yarn build && typedoc --excludeExternals --includeDeclarations --plugin ./dist/index.js --hideSources --hideIndexes --out ../docs/Cube.js-Frontend --name @cubejs-client-core ../packages/cubejs-client-core/index.d.ts",
1212
"dev-generate": "copyfiles --up 1 ./src/**/*.hbs ./dist/ && yarn generate",
1313
"build": "rm -rf dist && tsc --sourceMap false --declaration false && copyfiles --up 1 ./src/**/*.hbs ./dist/",
1414
"watch": "tsc-watch",

‎docs-gen/src/CubejsGroupPlugin.ts

Lines changed: 53 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
import { ReflectionKind, Reflection, ContainerReflection, DeclarationReflection } from 'typedoc';
2-
// import { CubejsGroupPlugin } from 'typedoc/dist/lib/converter/plugins';
32
import { Component } from 'typedoc/dist/lib/utils';
43
import { Converter, Context } from 'typedoc/dist/lib/converter';
5-
import { SourceDirectory, ReflectionGroup } from 'typedoc/dist/lib/models';
6-
import {ConverterComponent} from 'typedoc/dist/lib/converter/components';
4+
import { SourceDirectory, ReflectionGroup, Comment } from 'typedoc/dist/lib/models';
5+
import { ConverterComponent } from 'typedoc/dist/lib/converter/components';
76

87
@Component({ name: 'cubejs-group' })
98
export default class CubejsGroupPlugin extends ConverterComponent {
@@ -12,6 +11,7 @@ export default class CubejsGroupPlugin extends ConverterComponent {
1211
*/
1312
static WEIGHTS = [
1413
ReflectionKind.Class,
14+
ReflectionKind.Function,
1515
ReflectionKind.Global,
1616
ReflectionKind.Module,
1717
ReflectionKind.Namespace,
@@ -24,7 +24,6 @@ export default class CubejsGroupPlugin extends ConverterComponent {
2424
ReflectionKind.Event,
2525
ReflectionKind.Property,
2626
ReflectionKind.Variable,
27-
ReflectionKind.Function,
2827
ReflectionKind.Accessor,
2928
ReflectionKind.Method,
3029
ReflectionKind.ObjectLiteral,
@@ -62,26 +61,60 @@ export default class CubejsGroupPlugin extends ConverterComponent {
6261
return plurals;
6362
})();
6463

64+
static orderByName = new Map<string, number>();
65+
6566
/**
6667
* Create a new CubejsGroupPlugin instance.
6768
*/
6869
initialize() {
69-
this.listenTo(this.owner, {
70-
[Converter.EVENT_RESOLVE]: this.onResolve,
71-
[Converter.EVENT_RESOLVE_END]: this.onEndResolve,
72-
}, null, 1);
70+
this.listenTo(
71+
this.owner,
72+
{
73+
[Converter.EVENT_RESOLVE]: this.onResolve,
74+
[Converter.EVENT_RESOLVE_END]: this.onEndResolve,
75+
},
76+
null,
77+
1
78+
);
79+
}
80+
81+
private populateOrder(children: Reflection[] = []) {
82+
const MAGIC = 100_000;
83+
84+
function findOrderAndRemove(comment?: Comment) {
85+
const orderTag = (comment?.tags || []).find((tag) => tag.tagName === 'order');
86+
87+
if (orderTag) {
88+
comment.tags = (comment.tags || []).filter((tag) => tag.tagName !== 'order');
89+
return parseInt(orderTag.text, 10) - MAGIC;
90+
}
91+
}
92+
93+
function getOrder(reflection: Reflection) {
94+
if (reflection.hasComment()) {
95+
return findOrderAndRemove(reflection.comment);
96+
} else if (reflection instanceof DeclarationReflection) {
97+
return findOrderAndRemove(reflection.signatures?.[0]?.comment);
98+
}
99+
100+
return 0;
101+
}
102+
103+
children.forEach((reflection) => {
104+
if (!CubejsGroupPlugin.orderByName.has(reflection.name)) {
105+
CubejsGroupPlugin.orderByName.set(reflection.name, getOrder(reflection) || 0);
106+
}
107+
});
73108
}
74109

75110
private onResolve(context: Context, reflection: ContainerReflection) {
76111
reflection.kindString = CubejsGroupPlugin.getKindSingular(reflection.kind);
77-
78-
// if (reflection instanceof ContainerReflection) {
79-
80-
if (reflection.children && reflection.children.length > 0) {
81-
reflection.children.sort(CubejsGroupPlugin.sortCallback);
82-
reflection.groups = CubejsGroupPlugin.getReflectionGroups(reflection.children);
83-
}
84-
// }
112+
113+
if (reflection.children && reflection.children.length > 0) {
114+
this.populateOrder(reflection.children);
115+
reflection.children.sort(CubejsGroupPlugin.sortCallback);
116+
reflection.groups = CubejsGroupPlugin.getReflectionGroups(reflection.children);
117+
}
85118
}
86119

87120
/**
@@ -103,6 +136,7 @@ export default class CubejsGroupPlugin extends ConverterComponent {
103136

104137
const project = context.project;
105138
if (project.children && project.children.length > 0) {
139+
this.populateOrder(project.children);
106140
project.children.sort(CubejsGroupPlugin.sortCallback);
107141
project.groups = CubejsGroupPlugin.getReflectionGroups(project.children);
108142
}
@@ -216,8 +250,9 @@ export default class CubejsGroupPlugin extends ConverterComponent {
216250
* @returns The sorting weight.
217251
*/
218252
static sortCallback(a: Reflection, b: Reflection): number {
219-
const aWeight = CubejsGroupPlugin.WEIGHTS.indexOf(a.kind);
220-
const bWeight = CubejsGroupPlugin.WEIGHTS.indexOf(b.kind);
253+
const aWeight = CubejsGroupPlugin.orderByName.get(a.name) || CubejsGroupPlugin.WEIGHTS.indexOf(a.kind);
254+
const bWeight = CubejsGroupPlugin.orderByName.get(b.name) || CubejsGroupPlugin.WEIGHTS.indexOf(b.kind);
255+
221256
if (aWeight === bWeight) {
222257
if (a.flags.isStatic && !b.flags.isStatic) {
223258
return 1;

‎docs-gen/src/plugin.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import * as path from 'path';
2-
import * as fs from 'fs';
2+
import * as fs from 'fs-extra';
33
import { Renderer } from 'typedoc';
44
import { Converter } from 'typedoc/dist/lib/converter';
55
import { Component, ConverterComponent } from 'typedoc/dist/lib/converter/components';
@@ -58,7 +58,7 @@ export class MarkdownPlugin extends ConverterComponent {
5858
fs.copyFileSync(path.join(tmpOut, fileName), currentPath);
5959
});
6060

61-
fs.rmdirSync(tmpOut, { recursive: true });
61+
fs.removeSync(tmpOut);
6262
}
6363
})
6464
}

‎docs-gen/src/resources/helpers/declaration-title.ts

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@ import { heading } from './heading';
33
import { memberSymbol } from './member-symbol';
44
import { type } from './type';
55

6-
export function declarationTitle(this: DeclarationReflection, showSymbol: boolean) {
7-
const isOptional = this.flags.map(flag => flag).includes('Optional');
6+
export function declarationTitle(this: DeclarationReflection, showSymbol: boolean) {
7+
if (this.type?.type !== 'union') {
8+
return '';
9+
}
810

911
const md = [];
10-
11-
if (this.parent && this.parent.kind !== ReflectionKind.ObjectLiteral && this.kind === ReflectionKind.ObjectLiteral) {
12+
const isOptional = this.flags.map(flag => flag).includes('Optional');
13+
14+
if (this.parent && this.parent.kind !== ReflectionKind.ObjectLiteral) {
1215
md.push(heading(3));
1316
}
1417

@@ -24,5 +27,6 @@ export function declarationTitle(this: DeclarationReflection, showSymbol: boolea
2427
if (this.defaultValue) {
2528
md.push(`= ${this.defaultValue}`);
2629
}
30+
2731
return md.join(' ');
2832
}

‎docs-gen/src/resources/helpers/if-cond.ts

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/**
2+
* Handlebars if helper with condition.
3+
*
4+
* @param v1 The first value to be compared.
5+
* @param operator The operand to perform on the two given values.
6+
* @param v2 The second value to be compared
7+
* @param options The current handlebars object.
8+
* @param this The current handlebars this.
9+
* @returns {*}
10+
*/
11+
export function ifCond(v1: any, operator: any, v2: any, options: any) {
12+
switch (operator) {
13+
case '==':
14+
return v1 == v2 ? options.fn(this) : options.inverse(this);
15+
case '!=':
16+
return v1 != v2 ? options.fn(this) : options.inverse(this);
17+
case '===':
18+
return v1 === v2 ? options.fn(this) : options.inverse(this);
19+
case '<':
20+
return v1 < v2 ? options.fn(this) : options.inverse(this);
21+
case '<=':
22+
return v1 <= v2 ? options.fn(this) : options.inverse(this);
23+
case '>':
24+
return v1 > v2 ? options.fn(this) : options.inverse(this);
25+
case '>=':
26+
return v1 >= v2 ? options.fn(this) : options.inverse(this);
27+
case '&&':
28+
return v1 && v2 ? options.fn(this) : options.inverse(this);
29+
case '||':
30+
return v1 || v2 ? options.fn(this) : options.inverse(this);
31+
default:
32+
return options.inverse(this);
33+
}
34+
}

‎docs-gen/src/resources/helpers/meta.ts

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { ProjectReflection } from 'typedoc';
2+
import { CommentTag, ContainerReflection } from 'typedoc/dist/lib/models';
3+
4+
export function meta(this: ProjectReflection) {
5+
function findModuleRelection(reflection: ContainerReflection) {
6+
if (reflection.comment) {
7+
return reflection;
8+
}
9+
10+
return findModuleRelection(reflection.children?.[0]);
11+
}
12+
13+
const moduleReflection = findModuleRelection(this);
14+
15+
if (moduleReflection) {
16+
const { comment } = moduleReflection;
17+
const md = ['---'];
18+
19+
(comment?.tags || []).forEach((tag: CommentTag) => {
20+
if (tag.tagName !== 'description') {
21+
md.push(`${tag.tagName}: ${tag.text}`.replace('\n', ''));
22+
}
23+
});
24+
md.push('---');
25+
const description = (comment?.tags || []).find((tag: CommentTag) => tag.tagName === 'description');
26+
27+
if (description) {
28+
md.push('');
29+
md.push(description.text);
30+
}
31+
32+
return md.join('\n');
33+
}
34+
35+
return '';
36+
}

‎docs-gen/src/resources/helpers/signature-title.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { SignatureReflection } from 'typedoc';
1+
import { SignatureReflection, ReflectionKind } from 'typedoc';
22

33
import { memberSymbol } from './member-symbol';
44
import { type } from './type';

‎docs-gen/src/resources/partials/main.hbs

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
1-
{{#ifCond kindString '==' 'Module'}}
2-
{{> index}}
1+
{{meta}}
32

43
{{> members}}
5-
{{else}}
6-
{{#ifIndexes}}
7-
{{> index}}
8-
9-
{{/ifIndexes}}
10-
{{> members}}
11-
{{/ifCond}}

‎docs-gen/src/resources/partials/member.declaration.hbs

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
1+
{{!-- {{#if type.declaration}}
2+
13
{{{declarationTitle true}}}
24
3-
{{> member.sources}}
5+
{{/if}} --}}
6+
{{{declarationTitle true}}}
47

58
{{> comment}}
69

710
{{#if type.declaration}}
811

9-
{{heading 4}} Type declaration:
12+
{{#with type.declaration.children}}
1013

11-
{{#with type.declaration}}
12-
13-
{{> parameter}}
14+
{{{parameterTable}}}
1415

1516
{{/with}}
17+
{{!-- {{> parameter}} --}}
18+
1619

1720
{{/if}}

‎docs-gen/src/resources/partials/member.hbs

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1+
{{#ifCond kindString '!=' 'Module'}}
12
{{#if name}}
23

34
{{#ifParentIsModule true}}
45

5-
{{heading 2}}{{{ memberTitle }}}
6+
{{heading 2}} {{{ memberTitle }}}
67

78
{{else}}
89

@@ -11,6 +12,7 @@
1112
{{/ifParentIsModule}}
1213

1314
{{/if}}
15+
{{/ifCond}}
1416

1517
{{#if signatures}}
1618

@@ -28,8 +30,14 @@
2830

2931
{{else}}
3032

33+
{{#ifCond kindString '!=' 'Module'}}
34+
{{!-- {{#ifParentIsModule false}} --}}
35+
3136
{{> member.declaration}}
3237

38+
{{!-- {{/ifParentIsModule}} --}}
39+
{{/ifCond}}
40+
3341
{{/if}}
3442

3543
{{/if}}

0 commit comments

Comments
 (0)