feat(tsdocs): make it possible to run api-extractor on a package

Use --package-only flag

Author: raymondfeng

.gitignore

@@ -12,6 +12,7 @@ benchmark/dist
 .sandbox
 packages/cli/generators/datasource/connectors.json
 packages/tsdocs/fixtures/monorepo/docs
+packages/tsdocs/fixtures/monorepo/packages/pkg1/docs
 /docs/site/readmes
 /docs/apidocs/reports-temp
 /docs/apidocs/models

packages/tsdocs/bin/extract-apis.js

@@ -7,17 +7,23 @@
 /**
  * Run api-extractor against the monorepo
  */
-const runExtractorForMonorepo = require('..').runExtractorForMonorepo;
+const {runExtractorForMonorepo, runExtractorForPackage} = require('..');
 
 const silent = process.argv.includes('--silent');
 const dryRun = process.argv.includes('--dry-run');
 
+const pkgOnly = process.argv.includes('--package-only');
+
 /**
  * The option to control if reports are generated by api-extractor
  */
 const apiReportEnabled = process.argv.includes('--report');
 
 async function main() {
+  if (pkgOnly) {
+    runExtractorForPackage({silent, dryRun});
+    return;
+  }
   await runExtractorForMonorepo({silent, dryRun, apiReportEnabled});
 }
 

packages/tsdocs/bin/update-apidocs.js

@@ -8,6 +8,7 @@ import * as fs from 'fs-extra';
 import pEvent from 'p-event';
 import * as path from 'path';
 import {runExtractorForMonorepo, updateApiDocs} from '../..';
+import {runExtractorForPackage} from '../../monorepo-api-extractor';
 import {fixConstructorName} from '../../update-api-md-docs';
 
 const runCLI = require('@loopback/build').runCLI;
@@ -35,6 +36,7 @@ describe('tsdocs', function() {
   before('remove apidocs', () => {
     fs.emptyDirSync(APIDOCS_ROOT);
     fs.emptyDirSync(SITE_APIDOCS_ROOT);
+    fs.emptyDirSync(path.join(MONOREPO_ROOT, 'packages/pkg1/docs'));
   });
 
   it('runs api-extractor', async () => {
@@ -55,6 +57,26 @@ describe('tsdocs', function() {
     expect(reports.sort()).to.eql(['pkg1.api.md', 'pkg2.api.md']);
   });
 
+  it('runs api-extractor on package only', async () => {
+    const pkgDir = path.join(MONOREPO_ROOT, 'packages/pkg1');
+    const apidocsRootDir = path.join(pkgDir, 'docs/apidocs');
+
+    runExtractorForPackage(pkgDir, {
+      silent: true,
+      apiDocsGenerationPath: 'docs/apidocs',
+      apiReportEnabled: true,
+    });
+
+    const dirs = await fs.readdir(apidocsRootDir);
+    expect(dirs.sort()).eql(['models', 'reports', 'reports-temp']);
+
+    const models = await fs.readdir(path.join(apidocsRootDir, 'models'));
+    expect(models.sort()).to.eql(['pkg1.api.json']);
+
+    const reports = await fs.readdir(path.join(apidocsRootDir, 'reports'));
+    expect(reports.sort()).to.eql(['pkg1.api.md']);
+  });
+
   it('runs api-documenter', async () => {
     const args = [
       'markdown',

packages/tsdocs/src/__tests__/acceptance/tsdocs.acceptance.ts

@@ -65,18 +65,53 @@ export async function runExtractorForMonorepo(options: ExtractorOptions = {}) {
 
   for (const pkg of packages) {
     /* istanbul ignore if  */
-    if (!options.silent) {
-      console.log('> %s', pkg.name);
-    }
-    debug('Package: %s (%s)', pkg.name, pkg.location);
-
-    process.chdir(pkg.location);
+    invokeExtractorForPackage(pkg, options);
+  }
+}
 
-    const extractorConfig = buildExtractorConfig(pkg, options);
+export function runExtractorForPackage(
+  pkgDir: string = process.cwd(),
+  options: ExtractorOptions = {},
+) {
+  options = Object.assign(
+    {
+      rootDir: pkgDir,
+      apiDocsExtractionPath: DEFAULT_APIDOCS_EXTRACTION_PATH,
+      typescriptCompilerFolder: typeScriptPath,
+      tsconfigFilePath: 'tsconfig.build.json',
+      mainEntryPointFilePath: 'dist/index.d.ts',
+    },
+    options,
+  );
+  const pkgJson = require(path.join(pkgDir, 'package.json'));
+  setupApiDocsDirs(pkgDir, options);
+  const pkg: LernaPackage = {
+    private: pkgJson.private,
+    name: pkgJson.name,
+    location: pkgDir,
+    manifestLocation: path.join(pkgDir, 'package.json'),
+    rootPath: pkgDir,
+  };
+  invokeExtractorForPackage(pkg, options);
+}
 
-    debug('Resolved extractor config:', extractorConfig);
-    invokeExtractor(extractorConfig, options);
+/**
+ * Run `api-extractor` on a given package
+ * @param pkg - Package descriptor
+ * @param options - Options for api extraction
+ */
+function invokeExtractorForPackage(
+  pkg: LernaPackage,
+  options: ExtractorOptions,
+) {
+  if (!options.silent) {
+    console.log('> %s', pkg.name);
   }
+  debug('Package: %s (%s)', pkg.name, pkg.location);
+  process.chdir(pkg.location);
+  const extractorConfig = buildExtractorConfig(pkg, options);
+  debug('Resolved extractor config:', extractorConfig);
+  invokeExtractor(extractorConfig, options);
 }
 
 /**

packages/tsdocs/src/monorepo-api-extractor.ts

@@ -38,8 +38,10 @@ export async function updateApiDocs(options: ApiDocsOptions = {}) {
   /* istanbul ignore if  */
   if (!packages.length) return;
 
-  await addJekyllMetadata(packages[0].rootPath, options);
-  await generateIndex(packages, options);
+  const found = await addJekyllMetadata(packages[0].rootPath, options);
+  if (found) {
+    await generateIndex(packages, options);
+  }
 }
 
 /**
@@ -103,6 +105,11 @@ async function addJekyllMetadata(
   options: ApiDocsOptions,
 ) {
   const apiDocsRoot = path.join(lernaRootDir, options.apiDocsGenerationPath!);
+  const exists = await fs.pathExists(apiDocsRoot);
+  if (!exists) {
+    console.error('No API docs found at %s.', apiDocsRoot);
+    return false;
+  }
   const apiFiles = await fs.readdir(apiDocsRoot);
   for (const f of apiFiles) {
     /* istanbul ignore if  */
@@ -170,6 +177,7 @@ ${doc}
       }
     }
   }
+  return true;
 }
 
 // Fix `*.(constructor)`