From 6eb57737b2964a6d39964903f8d0a7bcf80a8cb0 Mon Sep 17 00:00:00 2001 From: Raymond Feng Date: Tue, 11 Jun 2019 12:43:10 -0700 Subject: [PATCH] feat(tsdocs): make it possible to run api-extractor on a package Use --package-only flag --- .gitignore | 1 + packages/tsdocs/bin/extract-apis.js | 8 ++- packages/tsdocs/bin/update-apidocs.js | 0 .../__tests__/acceptance/tsdocs.acceptance.ts | 22 ++++++++ packages/tsdocs/src/monorepo-api-extractor.ts | 53 +++++++++++++++---- packages/tsdocs/src/update-api-md-docs.ts | 12 ++++- 6 files changed, 84 insertions(+), 12 deletions(-) mode change 100644 => 100755 packages/tsdocs/bin/extract-apis.js mode change 100644 => 100755 packages/tsdocs/bin/update-apidocs.js diff --git a/.gitignore b/.gitignore index b6ffafa1aea0..86fc182f4989 100644 --- a/.gitignore +++ b/.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 diff --git a/packages/tsdocs/bin/extract-apis.js b/packages/tsdocs/bin/extract-apis.js old mode 100644 new mode 100755 index 878c603611f7..2de5758f9c1b --- a/packages/tsdocs/bin/extract-apis.js +++ b/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}); } diff --git a/packages/tsdocs/bin/update-apidocs.js b/packages/tsdocs/bin/update-apidocs.js old mode 100644 new mode 100755 diff --git a/packages/tsdocs/src/__tests__/acceptance/tsdocs.acceptance.ts b/packages/tsdocs/src/__tests__/acceptance/tsdocs.acceptance.ts index 1fd55831c0c8..2210274b0912 100644 --- a/packages/tsdocs/src/__tests__/acceptance/tsdocs.acceptance.ts +++ b/packages/tsdocs/src/__tests__/acceptance/tsdocs.acceptance.ts @@ -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', diff --git a/packages/tsdocs/src/monorepo-api-extractor.ts b/packages/tsdocs/src/monorepo-api-extractor.ts index 5471df12e0b6..328880338229 100644 --- a/packages/tsdocs/src/monorepo-api-extractor.ts +++ b/packages/tsdocs/src/monorepo-api-extractor.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); } /** diff --git a/packages/tsdocs/src/update-api-md-docs.ts b/packages/tsdocs/src/update-api-md-docs.ts index cfbb8b096d47..48ad83bc48d2 100644 --- a/packages/tsdocs/src/update-api-md-docs.ts +++ b/packages/tsdocs/src/update-api-md-docs.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)`