feat: export replaceMarkdownPlaceholders, parse returns a function

Author: adamdbradley

README.md

@@ -27,7 +27,7 @@ Below is an index of all the methods available.
 <!--DOCGEN_INDEX_START-->
 <!--DOCGEN_INDEX_END-->
 
-## Custom Content
+## Custom Readme Content
 
 Manage your readme content however you'd like, and on every docgen 
 rebuild it will leave your original content as is, but update the 

bin/docgen

@@ -3,21 +3,25 @@ import { parse } from './parse';
 import { outputJson, outputReadme } from './output';
 
 /**
- * Given the input files, will return generated results and optionally
- * write the data as a json file, readme, or both.
+ * Given a tsconfig file path, or input files, will return generated
+ * results and optionally write the data as a json file, readme, or both.
  */
 export async function generate(opts: DocsGenerateOptions) {
+  const apiFinder = parse(opts);
+
+  const data = apiFinder(opts.api);
+
   const results: DocsGenerateResults = {
     ...opts,
-    data: await parse(opts),
+    data,
   };
 
   if (opts.outputJsonPath) {
-    await outputJson(opts.outputJsonPath, results.data);
+    await outputJson(opts.outputJsonPath, data);
   }
 
   if (opts.outputReadmePath) {
-    await outputReadme(opts.outputReadmePath, results.data);
+    await outputReadme(opts.outputReadmePath, data);
   }
 
   return results;

src/generate.ts

@@ -1,5 +1,9 @@
 export { generate } from './generate';
-export { outputJson, outputReadme } from './output';
+export {
+  outputJson,
+  outputReadme,
+  replaceMarkdownPlaceholders,
+} from './output';
 export { parse } from './parse';
 export { run } from './cli';
 export * from './types';

src/index.ts

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import path from 'path';
 import { promisify } from 'util';
 import { MarkdownTable } from './markdown';
 import type {
@@ -14,6 +15,12 @@ const readFile = promisify(fs.readFile);
 const writeFile = promisify(fs.writeFile);
 
 export async function outputReadme(readmeFilePath: string, data: DocsData) {
+  if (typeof readmeFilePath !== 'string') {
+    throw new Error(`Missing readme file path`);
+  }
+  if (!path.isAbsolute(readmeFilePath)) {
+    throw new Error(`Readme file path must be an absolute path`);
+  }
   let content: string;
   try {
     content = await readFile(readmeFilePath, 'utf8');
@@ -23,16 +30,20 @@ export async function outputReadme(readmeFilePath: string, data: DocsData) {
     );
   }
 
-  content = replaceMarkdownDocs(content, data);
+  content = replaceMarkdownPlaceholders(content, data);
   await writeFile(readmeFilePath, content);
 }
 
-export function replaceMarkdownDocs(content: string, data: DocsData) {
-  if (data?.api) {
-    data = JSON.parse(JSON.stringify(data));
-    content = replaceMarkdownDocsIndex(content, data);
-    content = replaceMarkdownDocsApi(content, data);
+export function replaceMarkdownPlaceholders(content: string, data: DocsData) {
+  if (typeof content !== 'string') {
+    throw new Error(`Invalid content`);
+  }
+  if (data == null || data.api == null) {
+    throw new Error(`Missing data`);
   }
+  data = JSON.parse(JSON.stringify(data));
+  content = replaceMarkdownDocsIndex(content, data);
+  content = replaceMarkdownDocsApi(content, data);
   return content;
 }
 
@@ -93,6 +104,11 @@ function markdownIndex(data: DocsData) {
 function markdownApi(data: DocsData) {
   const o: string[] = [];
 
+  if (typeof data.api?.docs === 'string' && data.api.docs.length > 0) {
+    o.push(data.api.docs);
+    o.push(``);
+  }
+
   o.push(`## API`);
   o.push(``);
 
@@ -313,6 +329,15 @@ function getTagText(tags: DocsTagInfo[], tagName: string) {
 }
 
 export async function outputJson(jsonFilePath: string, data: DocsData) {
+  if (typeof jsonFilePath !== 'string') {
+    throw new Error(`Missing json file path`);
+  }
+  if (!path.isAbsolute(jsonFilePath)) {
+    throw new Error(`JSON file path must be an absolute path`);
+  }
+  if (data == null) {
+    throw new Error(`Missing data`);
+  }
   const content = JSON.stringify(data, null, 2);
   await writeFile(jsonFilePath, content);
 }

src/output.ts

@@ -13,8 +13,14 @@ import type {
 import { getTsProgram } from './transpile';
 import GithubSlugger from 'github-slugger';
 
+/**
+ * Given either a tsconfig file path, or exact input files, will
+ * use TypeScript to parse apart the source file's JSDoc comments
+ * and returns a function which can be used to get a specific
+ * interface as the primary api. Used by the generate() function.
+ */
 export function parse(opts: DocsParseOptions) {
-  const tsProgram = getTsProgram(opts.tsconfigPath);
+  const tsProgram = getTsProgram(opts);
   const typeChecker = tsProgram.getTypeChecker();
   const tsSourceFiles = tsProgram.getSourceFiles();
 
@@ -25,19 +31,21 @@ export function parse(opts: DocsParseOptions) {
     parseSourceFile(tsSourceFile, typeChecker, interfaces, enums);
   });
 
-  const api = interfaces.find(i => i.name === opts.api) || null;
+  return (api: string) => {
+    const apiInterface = interfaces.find(i => i.name === api) || null;
 
-  const data: DocsData = {
-    api,
-    interfaces: [],
-    enums: [],
-  };
+    const data: DocsData = {
+      api: apiInterface,
+      interfaces: [],
+      enums: [],
+    };
 
-  if (api) {
-    collectInterfaces(data, api, interfaces, enums);
-  }
+    if (apiInterface) {
+      collectInterfaces(data, apiInterface, interfaces, enums);
+    }
 
-  return data;
+    return data;
+  };
 }
 
 function collectInterfaces(

src/parse.ts

@@ -15,14 +15,21 @@ Below is an index of all the methods available.
 * [Enums](#enums)
 <!--DOCGEN_INDEX_END-->
 
-## Custom Content
+## Custom Readme Content
 
 Manage your readme content however you'd like, and on every docgen 
 rebuild it will leave your original content as is, but update the 
 HTML placeholder comments with the updated generated docs.
 
 <!--DOCGEN_API_START-->
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+## Docs from JSDoc comments!
+
+This content is from the JSDOC comments on top of
+the `HapticsPlugin` interface. All the API data below
+is generated from comments from its methods, interfaces
+and enums.
+
 ## API
 
 ### impact

src/test/README.md

@@ -2,7 +2,7 @@
   "api": {
     "name": "HapticsPlugin",
     "slug": "hapticsplugin",
-    "docs": "Top level docs.",
+    "docs": "## Docs from JSDoc comments!\n\nThis content is from the JSDOC comments on top of\nthe `HapticsPlugin` interface. All the API data below\nis generated from comments from its methods, interfaces\nand enums.",
     "tags": [],
     "methods": [
       {

src/test/docs.json

@@ -1,5 +1,10 @@
 /**
- * Top level docs.
+ * ## Docs from JSDoc comments!
+ *
+ * This content is from the JSDOC comments on top of
+ * the `HapticsPlugin` interface. All the API data below
+ * is generated from comments from its methods, interfaces
+ * and enums.
  */
 export interface HapticsPlugin {
   /**

src/test/fixtures/definitions.ts

@@ -2,11 +2,12 @@ import { parse } from '../parse';
 import path from 'path';
 
 describe('parse', () => {
-  const { api, interfaces, enums } = parse({
+  const apiFinder = parse({
     tsconfigPath: path.join(__dirname, 'fixtures', 'tsconfig.json'),
-    api: 'HapticsPlugin',
   });
 
+  const { api, interfaces, enums } = apiFinder('HapticsPlugin');
+
   it('api', () => {
     expect(api.name).toBe(`HapticsPlugin`);
     expect(api.slug).toBe(`hapticsplugin`);

src/test/parse.spec.ts

@@ -1,23 +1,41 @@
 import ts from 'typescript';
 import fs from 'fs';
 import path from 'path';
+import { DocsParseOptions } from './types';
 
-export function getTsProgram(tsconfigPath: string) {
-  const configResult = ts.readConfigFile(tsconfigPath, p =>
-    fs.readFileSync(p, 'utf-8'),
-  );
+export function getTsProgram(opts: DocsParseOptions) {
+  let rootNames: string[];
+  let options: ts.CompilerOptions;
 
-  if (configResult.error) {
+  if (typeof opts.tsconfigPath === 'string') {
+    const configResult = ts.readConfigFile(opts.tsconfigPath, p =>
+      fs.readFileSync(p, 'utf-8'),
+    );
+
+    if (configResult.error) {
+      throw new Error(
+        `Unable to read tsconfig path: "${opts.tsconfigPath}". ` +
+          ts.flattenDiagnosticMessageText(configResult.error.messageText, '\n'),
+      );
+    }
+    const tsconfigDir = path.dirname(opts.tsconfigPath);
+    rootNames = configResult.config.files.map((f: string) => {
+      return path.join(tsconfigDir, f);
+    });
+    options = configResult.config.compilerOptions;
+  } else if (Array.isArray(opts.inputFiles) && opts.inputFiles.length > 0) {
+    opts.inputFiles.forEach(i => {
+      if (!path.isAbsolute(i)) {
+        throw new Error(`inputFile "${i}" must be absolute`);
+      }
+    });
+    options = {};
+    rootNames = [...opts.inputFiles];
+  } else {
     throw new Error(
-      `Unable to read tsconfig path: "${tsconfigPath}". ` +
-        ts.flattenDiagnosticMessageText(configResult.error.messageText, '\n'),
+      `Either "tsconfigPath" or "inputFiles" option must be provided`,
     );
   }
-  const tsconfigDir = path.dirname(tsconfigPath);
-  const rootNames = configResult.config.files.map((f: string) => {
-    return path.join(tsconfigDir, f);
-  });
-  const options = configResult.config.compilerOptions;
 
   // same defaults as transpile() for faster parse-only transpiling
   options.isolatedModules = true;

src/transpile.ts

@@ -70,11 +70,12 @@ export interface DocsTagInfo {
 }
 
 export interface DocsParseOptions {
-  tsconfigPath: string;
-  api: string;
+  tsconfigPath?: string;
+  inputFiles?: string[];
 }
 
 export interface DocsGenerateOptions extends DocsParseOptions {
+  api: string;
   outputJsonPath?: string;
   outputReadmePath?: string;
 }