Skip to content

Commit

Permalink
chore(tsdocs): generate index.md for apidocs
Browse files Browse the repository at this point in the history
  • Loading branch information
raymondfeng committed May 6, 2019
1 parent 2ff66d4 commit 397b119
Show file tree
Hide file tree
Showing 12 changed files with 245 additions and 53 deletions.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ benchmark/dist
.sandbox
packages/cli/generators/datasource/connectors.json
docs/site/readmes
docs/apidocs/reports-temp
docs/apidocs/models

# Exclude all files under sandbox except README.md and example
/sandbox/*
Expand Down
2 changes: 2 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
/coverage
**/*/api-docs
/docs/apidocs
/docs/site/apidocs
packages/cli/generators/*/templates
**/.sandbox
packages/*/dist
Expand Down
4 changes: 4 additions & 0 deletions docs/site/sidebars/lb4_sidebar.yml
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,10 @@ children:
url: FAQ.html
output: 'web, pdf'

- title: 'API docs'
url: apidocs.index.html
output: 'web, pdf'

- title: 'Reference'
url: Reference.html
output: 'web, pdf'
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
"version": "npm run update-packages && git add greenkeeper.json \"**/package-lock.json\" && npm run update-template-deps && npm run apidocs",
"outdated": "npm outdated --depth 0 && lerna exec --no-bail \"npm outdated --depth 0\"",
"apidocs": "node bin/run-lerna run build:apidocs",
"tsdocs": "lerna run --scope @loopback/tsdocs tsdocs",
"coverage:ci": "node packages/build/bin/run-nyc report --reporter=text-lcov | coveralls",
"precoverage": "npm test",
"coverage": "open coverage/index.html",
Expand Down
13 changes: 11 additions & 2 deletions packages/tsdocs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ It's built on top of https://api-extractor.com/:
### Build api reports and doc models

```sh
npm start
npm run extract-apidocs
```

The command above will traverse all TypeScript packages in the monorepo and run
Expand All @@ -27,12 +27,21 @@ The command above will traverse all TypeScript packages in the monorepo and run
### Generate api docs as markdown files

```sh
npm run generate-apidocs
npm run document-apidocs
```

It runs `api-documenter` to generate markdown files into
`loopback-next/docs/site/apidocs`.

### Update api docs for Jekyll site

```sh
npm run update-apidocs
```

It adds Jekyll metadata to markdown files in `loopback-next/docs/site/apidocs`
and generates `loopback-next/docs/site/Api-docs.md` as the index page.

## Installation

```sh
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,15 @@
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

/**
* Run api-extractor against the monorepo
*/
const runExtractorForMonorepo = require('..').runExtractorForMonorepo;
const silent = process.argv.includes('--silent');
const dryRun = process.argv.includes('--dry-run');

runExtractorForMonorepo({silent, dryRun});
async function main() {
await runExtractorForMonorepo({silent, dryRun});
}

main();
18 changes: 18 additions & 0 deletions packages/tsdocs/bin/update-apidocs.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
#!/usr/bin/env node
// Copyright IBM Corp. 2019. All Rights Reserved.
// Node module: @loopback/tsdocs
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

/**
* Update generated api md files with Jekyll macros and create index page
*/
const updateApiDocs = require('..').updateApiDocs;
const silent = process.argv.includes('--silent');
const dryRun = process.argv.includes('--dry-run');

async function main() {
await updateApiDocs({silent, dryRun});
}

main();
12 changes: 5 additions & 7 deletions packages/tsdocs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,18 @@
"node": ">=8.9"
},
"private": true,
"bin": {
"tsdocs": "bin/cli.js"
},
"scripts": {
"acceptance": "lb-mocha \"dist/__tests__/acceptance/**/*.js\"",
"build:apidocs": "npm start && npm run -s generate-apidocs",
"generate-apidocs": "api-documenter markdown -i ../../docs/apidocs/models -o ../../docs/site/apidocs",
"tsdocs": "npm run build && npm run -s extract-apidocs && npm run -s document-apidocs && npm run -s update-apidocs",
"extract-apidocs": "node bin/extract-apis",
"document-apidocs": "api-documenter markdown -i ../../docs/apidocs/models -o ../../docs/site/apidocs",
"update-apidocs": "node bin/update-apidocs",
"build": "lb-tsc es2017 --outDir dist",
"clean": "lb-clean loopback-tsdocs*.tgz dist package api-docs",
"pretest": "npm run build",
"test": "lb-mocha \"dist/__tests__/**/*.js\"",
"unit": "lb-mocha \"dist/__tests__/unit/**/*.js\"",
"verify": "npm pack && tar xf loopback-tsdocs*.tgz && tree package && npm run clean",
"start": "npm run build && node bin/cli"
"verify": "npm pack && tar xf loopback-tsdocs*.tgz && tree package && npm run clean"
},
"author": "IBM Corp.",
"copyright.owner": "IBM Corp.",
Expand Down
76 changes: 76 additions & 0 deletions packages/tsdocs/src/helper.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
// Copyright IBM Corp. 2019. All Rights Reserved.
// Node module: @loopback/tsdocs
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

import * as fs from 'fs-extra';
import * as path from 'path';

const Project = require('@lerna/project');

/**
* TypeScript definition for Lerna Package
*/
export interface LernaPackage {
name: string;
location: string;
rootPath: string;
manifestLocation: string;
private: boolean;
}

/**
* Get unscoped package name
* @param name npm package name, such as `@loopback/context` or `express`
*/
export function getUnscopedPackageName(name: string) {
if (name.startsWith('@')) {
return name.split('/')[1];
}
return name;
}

/**
* Get lerna packages
* @param rootDir Root directory to find lerna.json
*/
export async function getPackages(
rootDir = process.cwd(),
): Promise<LernaPackage[]> {
const project = new Project(rootDir);
const packages: LernaPackage[] = await project.getPackages();
packages.sort((p1, p2) => p1.location.localeCompare(p2.location));
return packages;
}

/**
* Check if a package is TypeScript project
* @param pkg Lerna package
*/
export function isPublicTSPackage(pkg: LernaPackage) {
if (pkg.private) return false;
if (pkg.name.startsWith('@loopback/example-')) return false;

if (!fs.existsSync(path.join(pkg.location, 'tsconfig.build.json')))
return false;

if (!fs.existsSync(path.join(pkg.location, 'dist/index.d.ts'))) return false;

return true;
}

/**
* Get an array lerna-managed public TypeScript packages
* @param rootDir
*/
export async function getPublicTSPackages(
rootDir = process.cwd(),
): Promise<LernaPackage[]> {
const packages = await getPackages(rootDir);
return packages.filter(isPublicTSPackage);
}

/**
* Export the TypeScript path from `@loopback/build`
*/
export const typeScriptPath = require('@loopback/build').typeScriptPath;
1 change: 1 addition & 0 deletions packages/tsdocs/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

export * from './update-api-md-docs';
export * from './monorepo-api-extractor';
58 changes: 15 additions & 43 deletions packages/tsdocs/src/monorepo-api-extractor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,24 +16,9 @@ import {
import * as debugFactory from 'debug';
import * as fs from 'fs-extra';
import * as path from 'path';
import {getPublicTSPackages, typeScriptPath} from './helper';
const debug = debugFactory('loopback:tsdocs');

const Project = require('@lerna/project');

interface LernaPackage {
name: string;
location: string;
rootPath: string;
manifestLocation: string;
private: boolean;
}

async function getPackages(rootDir = process.cwd()): Promise<LernaPackage[]> {
const project = new Project(rootDir);
const packages = await project.getPackages();
return packages;
}

/**
* Options to run api-extractor against the lerna repo
*/
Expand Down Expand Up @@ -64,9 +49,6 @@ export interface ExtractorOptions {
typescriptCompilerFolder?: string;
}

const typeScriptPath = require('@loopback/build').typeScriptPath;
debug('TypeScript path: %s', typeScriptPath);

const DEFAULT_API_DOCS = 'docs/apidocs';

/**
Expand All @@ -87,35 +69,24 @@ export async function runExtractorForMonorepo(options: ExtractorOptions = {}) {

const apiDocsPath = options.apiDocsPath;

let compilerState: CompilerState | undefined = undefined;

const packages = await getPackages(options.rootDir);
const packages = await getPublicTSPackages(options.rootDir);
if (!packages.length) return;
const lernaRootDir = packages[0].rootPath;

if (packages.length && !options.silent) {
console.log(
'Running api-extractor for lerna repo: %s',
packages[0].rootPath,
);
if (!options.silent) {
console.log('Running api-extractor for lerna repo: %s', lernaRootDir);
}

for (const pkg of packages) {
debug('Package: %s (%s)', pkg.name, pkg.location);

if (pkg.private) continue;
fs.ensureDirSync(path.join(lernaRootDir, `${apiDocsPath}/reports`));

if (!fs.existsSync(path.join(pkg.location, 'tsconfig.build.json'))) {
continue;
}
const entryPoint = path.join(pkg.location, 'dist/index.d.ts');
if (!fs.existsSync(entryPoint)) {
continue;
for (const pkg of packages) {
if (!options.silent) {
console.log('> %s', pkg.name);
}

fs.ensureDirSync(path.join(pkg.rootPath, `${apiDocsPath}/reports`));
debug('Package: %s (%s)', pkg.name, pkg.location);

if (!options.silent) {
console.log(pkg.name);
}
const entryPoint = path.join(pkg.location, 'dist/index.d.ts');

process.chdir(pkg.location);

Expand Down Expand Up @@ -169,7 +140,7 @@ export async function runExtractorForMonorepo(options: ExtractorOptions = {}) {

debug('Resolved extractor config:', extractorConfig);

compilerState = CompilerState.create(extractorConfig, {
const compilerState = CompilerState.create(extractorConfig, {
// typescriptCompilerFolder: options.typescriptCompilerFolder,
});

Expand All @@ -182,7 +153,8 @@ export async function runExtractorForMonorepo(options: ExtractorOptions = {}) {
showVerboseMessages: !options.silent,
messageCallback: (message: ExtractorMessage) => {
if (message.messageId === ConsoleMessageId.ApiReportCreated) {
// This script deletes the outputs for a clean build, so don't issue a warning if the file gets created
// This script deletes the outputs for a clean build,
// so don't issue a warning if the file gets created
message.logLevel = ExtractorLogLevel.None;
}
},
Expand Down
Loading

0 comments on commit 397b119

Please sign in to comment.