Skip to content

Commit 2db19d3

Browse files
adamdbradleyadamdbradley
committed
feat(docs): generate api data
1 parent 6debb2a commit 2db19d3

17 files changed

Lines changed: 692 additions & 263 deletions

‎src/cli/parse-flags.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,7 @@ const ARG_OPTS = {
188188
string: [
189189
'address',
190190
'config',
191+
'docs-api',
191192
'docs-json',
192193
'emulate',
193194
'log-level',

‎src/compiler/build/build-ctx.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ export class BuildContext implements d.BuildCtx {
180180
}
181181

182182

183-
function getBuildTimestamp() {
183+
export function getBuildTimestamp() {
184184
const d = new Date();
185185

186186
// YYYY-MM-DDThh:mm:ss

‎src/compiler/config/_deprecated-validate-docs.ts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import * as d from '../../declarations';
2+
3+
/**
4+
* DEPRECATED "docs"
5+
* since 0.16.0, 2018-11-16
6+
*/
7+
export function _deprecatedDocsConfig(config: d.Config) {
8+
if (!config.outputTargets) {
9+
return;
10+
}
11+
12+
let jsonFile: string = null;
13+
14+
(config.outputTargets as any).forEach((outputTarget: any) => {
15+
if (outputTarget.type === 'docs') {
16+
17+
if (typeof outputTarget.jsonFile === 'string') {
18+
jsonFile = outputTarget.jsonFile;
19+
delete outputTarget.jsonFile;
20+
config.logger.warn(`Stencil config docs outputTarget using the "jsonFile" property has been refactored as a new outputTarget type "docs-json". Please see the stencil docs for more information.`);
21+
}
22+
23+
if (typeof outputTarget.readmeDir === 'string') {
24+
(outputTarget as d.OutputTargetDocsReadme).dir = outputTarget.readmeDir;
25+
delete outputTarget.readmeDir;
26+
config.logger.warn(`Stencil config docs outputTarget using the "readmeDir" property has been rename to "dir". Please see the stencil docs for more information.`);
27+
}
28+
}
29+
});
30+
31+
if (typeof jsonFile === 'string' && jsonFile) {
32+
(config.outputTargets as d.OutputTargetDocsJson[]).push({
33+
type: 'docs-json',
34+
file: jsonFile
35+
});
36+
}
37+
}

‎src/compiler/config/test/validate-docs.spec.ts‎

Lines changed: 57 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,20 @@ describe('validateDocs', () => {
2323
});
2424

2525

26-
it('docs default readmeDir', () => {
26+
it('readme docs dir', () => {
27+
config.flags.docs = true;
28+
config.outputTargets.push(
29+
{
30+
type: 'docs',
31+
dir: 'my-dir'
32+
} as d.OutputTargetDocs
33+
);
34+
validateConfig(config);
35+
const o = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
36+
expect(o.dir).toContain('my-dir');
37+
});
38+
39+
it('_deprecated: docs readmeDir', () => {
2740
config.flags.docs = true;
2841
config.outputTargets.push(
2942
{
@@ -33,11 +46,23 @@ describe('validateDocs', () => {
3346
);
3447
validateConfig(config);
3548
const o = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
36-
expect(o).toBeDefined();
37-
expect(o.readmeDir).toContain('my-dir');
49+
expect(o.dir).toContain('my-dir');
3850
});
3951

40-
it('docs, keep docs output target', () => {
52+
it('readme docs, keep docs output target', () => {
53+
config.flags.docs = true;
54+
config.outputTargets.push(
55+
{
56+
type: 'docs',
57+
dir: 'my-dir'
58+
} as d.OutputTargetDocs
59+
);
60+
validateConfig(config);
61+
const o = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
62+
expect(o.dir).toContain('my-dir');
63+
});
64+
65+
it('_deprecated: docs, keep docs output target', () => {
4166
config.flags.docs = true;
4267
config.outputTargets.push(
4368
{
@@ -47,27 +72,49 @@ describe('validateDocs', () => {
4772
);
4873
validateConfig(config);
4974
const o = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
50-
expect(o).toBeDefined();
51-
expect(o.readmeDir).toContain('my-dir');
75+
expect(o.dir).toContain('my-dir');
5276
});
5377

5478
it('docs-json w/ existing docs config', () => {
79+
config.flags.docsJson = 'some/path/docs.json';
80+
config.outputTargets.push(
81+
{
82+
type: 'docs-json'
83+
} as d.OutputTargetDocsJson
84+
);
85+
validateConfig(config);
86+
const o = config.outputTargets.find(o => o.type === 'docs-json') as d.OutputTargetDocsJson;
87+
expect(o.file).toContain('docs.json');
88+
});
89+
90+
it('_deprecated: docs-json w/ existing docs config', () => {
5591
config.flags.docsJson = 'some/path/docs.json';
5692
config.outputTargets.push(
5793
{
5894
type: 'docs'
5995
} as d.OutputTargetDocs
6096
);
6197
validateConfig(config);
62-
const o = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
63-
expect(o.jsonFile).toContain('docs.json');
98+
const depricated = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
99+
expect(depricated).toBeUndefined();
100+
const o = config.outputTargets.find(o => o.type === 'docs-json') as d.OutputTargetDocsJson;
101+
expect(o.file).toContain('docs.json');
64102
});
65103

66104
it('docs-json flag', () => {
67105
config.flags.docsJson = 'some/path/docs.json';
68106
validateConfig(config);
69-
const o = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
70-
expect(o.jsonFile).toContain('docs.json');
107+
const o = config.outputTargets.find(o => o.type === 'docs-json') as d.OutputTargetDocsJson;
108+
expect(o.file).toContain('docs.json');
109+
});
110+
111+
it('_deprecated: docs-json flag', () => {
112+
config.flags.docsJson = 'some/path/docs.json';
113+
validateConfig(config);
114+
const depricated = config.outputTargets.find(o => o.type === 'docs') as d.OutputTargetDocs;
115+
expect(depricated).toBeUndefined();
116+
const o = config.outputTargets.find(o => o.type === 'docs-json') as d.OutputTargetDocsJson;
117+
expect(o.file).toContain('docs.json');
71118
});
72119

73120
it('docs flag, and docs output target', () => {

‎src/compiler/config/validate-docs.ts‎

Lines changed: 84 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,112 @@
11
import * as d from '../../declarations';
22
import { pathJoin } from '../util';
3+
import { _deprecatedDocsConfig } from './_deprecated-validate-docs';
34

45

56
export function validateDocs(config: d.Config) {
6-
if (config.flags.docs || typeof config.flags.docsJson === 'string') {
7-
// docs flag
7+
_deprecatedDocsConfig(config);
8+
9+
if (typeof config.flags.docsApi === 'string') {
10+
// api docs flag
811
config.outputTargets = config.outputTargets || [];
912

10-
if (!config.outputTargets.some(o => o.type === 'docs')) {
13+
if (!(config.outputTargets as d.OutputTargetDocsApi[]).some(o => o.type === 'docs-api')) {
1114
// didn't provide a docs config, so let's add one
12-
const outputTarget: d.OutputTargetDocs = {
13-
type: 'docs'
15+
const outputTarget: d.OutputTargetDocsApi = {
16+
type: 'docs-api'
17+
};
18+
config.outputTargets.push(outputTarget);
19+
}
20+
21+
const apiDocsOutputs = (config.outputTargets as d.OutputTargetDocsApi[]).filter(o => o.type === 'docs-api');
22+
apiDocsOutputs.forEach(apiDocsOutput => {
23+
validateApiDocsOutputTarget(config, apiDocsOutput);
24+
});
25+
26+
} else if (config.outputTargets) {
27+
// remove api docs if there is no flag
28+
config.outputTargets = (config.outputTargets as d.OutputTargetDocsApi[]).filter(o => o.type !== 'docs-api');
29+
}
30+
31+
if (typeof config.flags.docsJson === 'string') {
32+
// json docs flag
33+
config.outputTargets = config.outputTargets || [];
34+
35+
if (!(config.outputTargets as d.OutputTargetDocsJson[]).some(o => o.type === 'docs-json')) {
36+
// didn't provide a docs config, so let's add one
37+
const outputTarget: d.OutputTargetDocsJson = {
38+
type: 'docs-json'
1439
};
1540
config.outputTargets.push(outputTarget);
1641
}
1742

18-
const docsOutputs = config.outputTargets.filter(o => o.type === 'docs') as d.OutputTargetDocs[];
19-
docsOutputs.forEach(outputTarget => {
20-
validateDocsOutputTarget(config, outputTarget);
43+
const jsonDocsOutputs = (config.outputTargets as d.OutputTargetDocsJson[]).filter(o => o.type === 'docs-json');
44+
jsonDocsOutputs.forEach(jsonDocsOutput => {
45+
validateJsonDocsOutputTarget(config, jsonDocsOutput);
2146
});
2247

23-
} else {
24-
if (config.outputTargets) {
25-
// remove docs if there is no docs flag
26-
config.outputTargets = config.outputTargets.filter(o => o.type !== 'docs');
48+
} else if (config.outputTargets) {
49+
// remove json docs if there is no flag
50+
config.outputTargets = (config.outputTargets as d.OutputTargetDocsJson[]).filter(o => o.type !== 'docs-json');
51+
}
52+
53+
if (config.flags.docs) {
54+
// readme docs flag
55+
config.outputTargets = config.outputTargets || [];
56+
57+
if (!(config.outputTargets as d.OutputTargetDocsReadme[]).some(o => o.type === 'docs')) {
58+
// didn't provide a docs config, so let's add one
59+
const outputTarget: d.OutputTargetDocsReadme = {
60+
type: 'docs'
61+
};
62+
config.outputTargets.push(outputTarget);
2763
}
64+
65+
const readmeDocsOutputs = (config.outputTargets as d.OutputTargetDocsReadme[]).filter(o => o.type === 'docs');
66+
readmeDocsOutputs.forEach(readmeDocsOutput => {
67+
validateReadmeOutputTarget(config, readmeDocsOutput);
68+
});
69+
70+
} else if (config.outputTargets) {
71+
// remove json docs if there is no flag
72+
config.outputTargets = (config.outputTargets as d.OutputTargetDocsReadme[]).filter(o => o.type !== 'docs');
73+
}
74+
}
75+
76+
77+
function validateReadmeOutputTarget(config: d.Config, outputTarget: d.OutputTargetDocsReadme) {
78+
if (config.flags.docs && typeof outputTarget.dir !== 'string') {
79+
outputTarget.dir = config.srcDir;
80+
}
81+
82+
if (typeof outputTarget.dir === 'string' && !config.sys.path.isAbsolute(outputTarget.dir)) {
83+
outputTarget.dir = pathJoin(config, config.rootDir, outputTarget.dir);
2884
}
85+
86+
outputTarget.strict = !!outputTarget.strict;
2987
}
3088

3189

32-
function validateDocsOutputTarget(config: d.Config, outputTarget: d.OutputTargetDocs) {
33-
if (typeof config.flags.docsJson === 'string' && typeof outputTarget.jsonFile !== 'string') {
34-
outputTarget.jsonFile = config.flags.docsJson;
90+
function validateJsonDocsOutputTarget(config: d.Config, outputTarget: d.OutputTargetDocsJson) {
91+
if (typeof config.flags.docsJson === 'string' && typeof outputTarget.file !== 'string') {
92+
outputTarget.file = config.flags.docsJson;
3593
}
3694

37-
if (config.flags.docs && typeof outputTarget.readmeDir !== 'string') {
38-
outputTarget.readmeDir = config.srcDir;
95+
if (typeof outputTarget.file === 'string') {
96+
outputTarget.file = pathJoin(config, config.rootDir, outputTarget.file);
3997
}
4098

41-
if (typeof outputTarget.readmeDir === 'string' && !config.sys.path.isAbsolute(outputTarget.readmeDir)) {
42-
outputTarget.readmeDir = pathJoin(config, config.rootDir, outputTarget.readmeDir);
99+
outputTarget.strict = !!outputTarget.strict;
100+
}
101+
102+
103+
function validateApiDocsOutputTarget(config: d.Config, outputTarget: d.OutputTargetDocsApi) {
104+
if (typeof config.flags.docsApi === 'string' && typeof outputTarget.file !== 'string') {
105+
outputTarget.file = config.flags.docsApi;
43106
}
44107

45-
if (typeof outputTarget.jsonFile === 'string') {
46-
outputTarget.jsonFile = pathJoin(config, config.rootDir, outputTarget.jsonFile);
108+
if (typeof outputTarget.file === 'string') {
109+
outputTarget.file = pathJoin(config, config.rootDir, outputTarget.file);
47110
}
48111

49112
outputTarget.strict = !!outputTarget.strict;

‎src/compiler/config/validate-outputs.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,4 @@ export function validateOutputTargets(config: d.Config) {
4545
}
4646

4747

48-
const VALID_TYPES = ['angular', 'dist', 'docs', 'stats', 'www'];
48+
const VALID_TYPES = ['angular', 'dist', 'docs', 'docs-json', 'stats', 'www'];

‎src/compiler/docs/docs.ts‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,12 @@ import * as d from '../../declarations';
22
import { BuildContext } from '../build/build-ctx';
33
import { catchError, hasError } from '../util';
44
import { cleanDiagnostics } from '../../util/logger/logger-util';
5-
import { generateReadmes } from './generate-readmes';
5+
import { generateApiDocs } from './generate-api-docs';
6+
import { generateDocData } from './generate-doc-data';
7+
import { generateJsonDocs } from './generate-json-docs';
8+
import { generateReadmeDocs } from './generate-readme-docs';
69
import { getCompilerCtx } from '../build/compiler-ctx';
10+
import { strickCheckDocs } from './strict-check';
711
import { transpileApp } from '../transpile/transpile-app';
812

913

@@ -48,9 +52,33 @@ export async function docs(config: d.Config, compilerCtx: d.CompilerCtx) {
4852

4953

5054
export async function generateDocs(config: d.Config, compilerCtx: d.CompilerCtx) {
51-
const docsOutputTargets = config.outputTargets.filter(o => o.type === 'docs') as d.OutputTargetDocs[];
55+
const docsOutputTargets = config.outputTargets.filter(o => {
56+
return o.type === 'docs' || o.type === 'docs-json' || o.type === 'docs-api';
57+
});
5258

53-
if (docsOutputTargets.length > 0) {
54-
await generateReadmes(config, compilerCtx, docsOutputTargets);
59+
if (docsOutputTargets.length === 0) {
60+
return;
61+
}
62+
63+
const docsData = await generateDocData(config, compilerCtx);
64+
65+
const strictCheck = (docsOutputTargets as d.OutputTargetDocsReadme[]).some(o => !!o.strict);
66+
if (strictCheck) {
67+
strickCheckDocs(config, docsData);
68+
}
69+
70+
const readmeTargets = (docsOutputTargets as d.OutputTargetDocsReadme[]).filter(o => o.type === 'docs');
71+
if (readmeTargets.length > 0) {
72+
await generateReadmeDocs(config, compilerCtx, readmeTargets, docsData);
73+
}
74+
75+
const jsonTargets = (docsOutputTargets as d.OutputTargetDocsJson[]).filter(o => o.type === 'docs-json');
76+
if (jsonTargets.length > 0) {
77+
await generateJsonDocs(config, compilerCtx, jsonTargets, docsData);
78+
}
79+
80+
const apiTargets = (docsOutputTargets as d.OutputTargetDocsApi[]).filter(o => o.type === 'docs-api');
81+
if (apiTargets.length > 0) {
82+
await generateApiDocs(compilerCtx, apiTargets, docsData);
5583
}
5684
}

0 commit comments

Comments
 (0)