feat(docs): custom docs generators (#1227)

* feat(docs): custom docs generators

* update generator signature

Author: manucorporat

src/compiler/config/validate-docs.ts

@@ -43,12 +43,17 @@ export function validateDocs(config: d.Config) {
       config.outputTargets.push({ type: 'docs' });
     }
   }
-
   const readmeDocsOutputs = config.outputTargets.filter(o => o.type === 'docs') as d.OutputTargetDocsReadme[];
   readmeDocsOutputs.forEach(readmeDocsOutput => {
     validateReadmeOutputTarget(config, readmeDocsOutput);
   });
 
+  // custom docs
+  const customDocsOutputs = config.outputTargets.filter(o => o.type === 'docs-custom') as d.OutputTargetDocsCustom[];
+  customDocsOutputs.forEach(jsonDocsOutput => {
+    validateCustomDocsOutputTarget(jsonDocsOutput);
+  });
+
   config.buildDocs = buildDocs;
 }
 
@@ -83,3 +88,12 @@ function validateApiDocsOutputTarget(config: d.Config, outputTarget: d.OutputTar
   outputTarget.file = pathJoin(config, config.rootDir, outputTarget.file);
   outputTarget.strict = !!outputTarget.strict;
 }
+
+
+function validateCustomDocsOutputTarget(outputTarget: d.OutputTargetDocsCustom) {
+  if (typeof outputTarget.generator !== 'function') {
+    throw new Error(`docs-custom outputTarget missing the "generator" function`);
+  }
+
+  outputTarget.strict = !!outputTarget.strict;
+}

src/compiler/config/validate-outputs.ts

@@ -45,4 +45,13 @@ export function validateOutputTargets(config: d.Config) {
 }
 
 
-const VALID_TYPES = ['angular', 'dist', 'docs', 'docs-json', 'docs-api', 'stats', 'www'];
+const VALID_TYPES = [
+  'angular',
+  'dist',
+  'docs',
+  'docs-json',
+  'docs-api',
+  'docs-custom',
+  'stats',
+  'www'
+];

src/compiler/docs/docs.ts

@@ -6,6 +6,7 @@ import { generateApiDocs } from './generate-api-docs';
 import { generateDocData } from './generate-doc-data';
 import { generateJsonDocs } from './generate-json-docs';
 import { generateReadmeDocs } from './generate-readme-docs';
+import { generateCustomDocs } from './generate-custom-docs';
 import { getCompilerCtx } from '../build/compiler-ctx';
 import { strickCheckDocs } from './strict-check';
 import { transpileApp } from '../transpile/transpile-app';
@@ -56,7 +57,7 @@ export async function generateDocs(config: d.Config, compilerCtx: d.CompilerCtx,
     return;
   }
   const docsOutputTargets = config.outputTargets.filter(o => {
-    return o.type === 'docs' || o.type === 'docs-json' || o.type === 'docs-api';
+    return o.type === 'docs' || o.type === 'docs-json' || o.type === 'docs-api' || o.type == 'docs-custom';
   });
 
   if (docsOutputTargets.length === 0) {
@@ -84,4 +85,9 @@ export async function generateDocs(config: d.Config, compilerCtx: d.CompilerCtx,
   if (apiTargets.length > 0) {
     await generateApiDocs(compilerCtx, apiTargets, docsData);
   }
+
+  const customTargets = docsOutputTargets.filter(o => o.type === 'docs-custom') as d.OutputTargetDocsCustom[];
+  if (customTargets.length > 0) {
+    await generateCustomDocs(config, customTargets, docsData);
+  }
 }

src/compiler/docs/generate-custom-docs.ts

@@ -0,0 +1,11 @@
+import * as d from '../../declarations';
+
+export async function generateCustomDocs(config: d.Config, customOutputs: d.OutputTargetDocsCustom[], docsData: d.JsonDocs) {
+  await Promise.all(customOutputs.map(async customOutput => {
+    try {
+      await customOutput.generator(docsData);
+    } catch (e) {
+      config.logger.error(`uncaught custom docs error: ${e}`);
+    }
+  }));
+}

src/declarations/output-targets.ts

@@ -1,4 +1,5 @@
 import * as d from '.';
+import { JsonDocs } from './docs';
 
 
 export interface OutputTargetWww extends OutputTargetBase {
@@ -192,6 +193,13 @@ export interface OutputTargetDocsApi extends OutputTargetBase {
   strict?: boolean;
 }
 
+export interface OutputTargetDocsCustom extends OutputTargetBase {
+  type: 'docs-custom';
+
+  generator: (docs: JsonDocs) => void | Promise<void>;
+  strict?: boolean;
+}
+
 
 export interface OutputTargetStats extends OutputTargetBase {
   type: 'stats';
@@ -228,6 +236,7 @@ export type OutputTarget =
  | OutputTargetStats
  | OutputTargetDocsApi
  | OutputTargetDocsJson
+ | OutputTargetDocsCustom
  | OutputTargetDocsReadme
  | OutputTargetHydrate
  | OutputTargetDist