Skip to content

Commit

Permalink
feat(compodoc): generate workspace docs
Browse files Browse the repository at this point in the history 
Adds an option flag to automatically include readmes of all projects, while the workspace's root readme becomes the documentation entry.
In workspace mode the includesName defaults to "Projects", but can still be overriden.
  • Loading branch information
@twittwer
twittwer committed May 2, 2020
1 parent 04402fb commit 3ab6578
Show file tree
Hide file tree
Showing 5 changed files with 106 additions and 59 deletions.
87 changes: 42 additions & 45 deletions libs/compodoc/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,47 +36,48 @@ The builder support several configuration options which are passed to Compodoc c
> [Original documentation of Compodoc options](https://compodoc.app/guides/options.html)
> (Defaults mainly correspond to the original default values - asterisks mark the exceptions)
| Option | Default | Description |
| --------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| tsConfig | `<projectRoot>/tsconfig.json` | Path to project's TypeScript configuration file. |
| outputPath | `dist/compodoc/<projectName>` | The output path of the generated files. |
| exportFormat | `html` | Output format (html, json). |
| | | |
| name | `<projectName>` | Title of the documentation. |
| language | `en-US` | Language used for the generated documentation. |
| | | |
| theme | `gitbook` | Theme used for the generated documentation. |
| extTheme | | Path to external theme file. |
| templates | | Path to directory of Handlebars templates to override built-in templates. |
| | | |
| customLogo | | Path to custom logo. |
| customFavicon | | Path to custom favicon. |
| hideGenerator | `false` | Do not print the Compodoc logo at the bottom of the page. |
| | | |
| includes | | Path of external markdown files to include (folder should contain a summary.json). |
| includesName | `Additional documentation` | Name of item menu of externals markdown files. |
| | | |
| disableCoverage | `true`\* | Do not add the documentation coverage report. |
| disableSourceCode | `false` | Do not add source code tab and links to source code. |
| disableDomTree | `false` | Do not add dom tree tab. |
| disableTemplateTab | `false` | Do not add template tab. |
| disableStyleTab | `false` | Do not add style tab. |
| disableGraph | `false` | Disable rendering of the dependency graph. |
| disablePrivate | `true`\* | Do not show private in generated documentation. |
| disableProtected | `false` | Do not show protected in generated documentation. |
| disableInternal | `true`\* | Do not show @internal in generated documentation. |
| disableLifeCycleHooks | `true`\* | Do not show Angular lifecycle hooks in generated documentation. |
| disableRoutesGraph | `false` | Do not add the routes graph. |
| disableSearch | `false` | Do not add the search input. |
| disableDependencies | `false` | Do not add the dependencies list. |
| | | |
| assetsFolder | | External assets folder to copy in generated documentation folder. |
| | | |
| serve | `false` | Serve generated documentation. |
| port | `8080` | Port for serving of documentation (default: 8080). |
| | | |
| silent | `true`\* | Suppress verbose build output. |
| | | |
| Option | Default | Description |
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| tsConfig | `<projectRoot>/tsconfig.json` | Path to project's TypeScript configuration file. |
| outputPath | `dist/compodoc/<projectName>` | The output path of the generated files. |
| exportFormat | `html` | Output format (html, json - enables Compodoc's `minimal` mode as well). |
| workspaceDocs | `false` | Use readme of workspace root as entry and add the readme files of all project as additional documentation. |
| | | |
| name | `<projectName>` | Title of the documentation. |
| language | `en-US` | Language used for the generated documentation. |
| | | |
| theme | `gitbook` | Theme used for the generated documentation. |
| extTheme | | Path to external theme file. |
| templates | | Path to directory of Handlebars templates to override built-in templates. |
| | | |
| customLogo | | Path to custom logo. |
| customFavicon | | Path to custom favicon. |
| hideGenerator | `false` | Do not print the Compodoc logo at the bottom of the page. |
| | | |
| includes | | Path to external markdown files, folder should contain a `summary.json`. (`workspaceDocs` will override this) |
| includesName | | Name of menu item containing external markdown files. (Defaults to "Projects" in `workspaceDocs` mode) |
| | | |
| disableCoverage | `true`\* | Do not add the documentation coverage report. |
| disableSourceCode | `false` | Do not add source code tab and links to source code. |
| disableDomTree | `false` | Do not add dom tree tab. |
| disableTemplateTab | `false` | Do not add template tab. |
| disableStyleTab | `false` | Do not add style tab. |
| disableGraph | `false` | Disable rendering of the dependency graph. |
| disablePrivate | `true`\* | Do not show private in generated documentation. |
| disableProtected | `false` | Do not show protected in generated documentation. |
| disableInternal | `true`\* | Do not show @internal in generated documentation. |
| disableLifeCycleHooks | `true`\* | Do not show Angular lifecycle hooks in generated documentation. |
| disableRoutesGraph | `false` | Do not add the routes graph. |
| disableSearch | `false` | Do not add the search input. |
| disableDependencies | `false` | Do not add the dependencies list. |
| | | |
| assetsFolder | | External assets folder to copy in generated documentation folder. |
| | | |
| serve | `false` | Serve generated documentation. |
| port | `8080` | Port for serving of documentation (default: 8080). |
| | | |
| silent | `true`\* | Suppress verbose build output. |
| | | |

> More details can be found in the builder's [schema.json](./src/builders/compodoc/schema.json).
Expand Down Expand Up @@ -105,7 +106,3 @@ The options can be defined in the `angular.json`:
},
}
```

## Planned Features

- Enable compodoc builder to generate a workspace wide documentation including the Readmes of all projects automatically.
4 changes: 2 additions & 2 deletions libs/compodoc/src/builders/compodoc/builder.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ async function runBuilder(

return new Promise<BuilderOutput>(res => {
const childProcess = spawn(
buildCompodocCmd(context),
buildCompodocCmd(options, context),
buildCompodocArgs(options, context),
{ cwd: projectRoot },
{ cwd: options.workspaceDocs ? workspaceRoot : projectRoot },
);

process.on('exit', () => childProcess.kill());
Expand Down
63 changes: 54 additions & 9 deletions libs/compodoc/src/builders/compodoc/compodoc-utils.ts
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,54 @@
import { BuilderContext } from '@angular-devkit/architect';
import { resolve } from 'path';
import { join, relative, resolve, sep } from 'path';
import { CompodocBuilderSchema } from './schema';
import { readWorkspaceJson } from '@nrwl/workspace';
import { WorkspaceSchema } from '@angular-devkit/core/src/experimental/workspace';
import { tmpdir } from 'os';
import { copyFileSync, existsSync, mkdtempSync, writeFileSync } from 'fs';

export function buildCompodocCmd({ workspaceRoot }: BuilderContext) {
export function buildCompodocCmd(
options: CompodocBuilderSchema,
context: BuilderContext,
) {
const { workspaceRoot } = context;
return resolve(workspaceRoot, 'node_modules', '.bin', 'compodoc');
}

function buildIncludesFolderForWorkspace(context: BuilderContext): string {
const { workspaceRoot } = context;
const { projects } = readWorkspaceJson() as WorkspaceSchema;

const tmpFolder = mkdtempSync(`${tmpdir()}${sep}`);

const summary = Object.entries(projects)
.map(([projectName, project]) => {
const projectReadme = `${projectName}.md`;
const projectReadmeOrigin = join(project.root, 'README.md');

if (existsSync(projectReadmeOrigin)) {
copyFileSync(projectReadmeOrigin, join(tmpFolder, projectReadme));
return {
title: projectName,
file: projectReadme,
};
}
})
.filter(Boolean);

writeFileSync(join(tmpFolder, 'summary.json'), JSON.stringify(summary));

return relative(workspaceRoot, tmpFolder);
}

export function buildCompodocArgs(
options: CompodocBuilderSchema,
{ workspaceRoot, target: { project } }: BuilderContext,
context: BuilderContext,
): string[] {
const {
workspaceRoot,
target: { project },
} = context;

const args: string[] = [];

const tsConfigPath = resolve(workspaceRoot, options.tsConfig);
Expand Down Expand Up @@ -52,15 +91,20 @@ export function buildCompodocArgs(
args.push('--hideGenerator');
}

if (options.includes) {
const includesPath = resolve(workspaceRoot, options.includes);
if (options.workspaceDocs) {
const includesPath = buildIncludesFolderForWorkspace(context);
args.push(`--includes=${includesPath}`);
args.push(`--includesName=${options.includesName ?? 'Projects'}`);
} else {
if (options.includes) {
const includesPath = resolve(workspaceRoot, options.includes);
args.push(`--includes=${includesPath}`);
}
if (options.includesName) {
args.push(`--includesName=${options.includesName}`);
}
}
args.push(`--includesName=${options.includesName}`);

if (options.hideGenerator) {
args.push('--hideGenerator');
}
if (options.disableCoverage) {
args.push('--disableCoverage');
}
Expand Down Expand Up @@ -101,6 +145,7 @@ export function buildCompodocArgs(
args.push('--disableDependencies');
}

// TODO: maybe use `<projectRoot>/src/assets` as default
if (options.assetsFolder) {
const assetsFolderPath = resolve(workspaceRoot, options.assetsFolder);
args.push(`--assetsFolder=${assetsFolderPath}`);
Expand Down
3 changes: 2 additions & 1 deletion libs/compodoc/src/builders/compodoc/schema.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ export interface CompodocBuilderSchema extends JsonObject {
tsConfig?: string;
outputPath?: string;
exportFormat: 'html' | 'json';
workspaceDocs: boolean;

name?: string;
language:
Expand Down Expand Up @@ -34,7 +35,7 @@ export interface CompodocBuilderSchema extends JsonObject {
hideGenerator: boolean;

includes?: string;
includesName: string;
includesName?: string;

disableCoverage: boolean;
disableSourceCode: boolean;
Expand Down
8 changes: 6 additions & 2 deletions libs/compodoc/src/builders/compodoc/schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,11 @@
{ "minLength": 1 }
]
},
"workspaceDocs": {
"description": "Use readme of workspace root as entry and add the readme files of all project as additional documentation.",
"type": "boolean",
"default": false
},

"name": {
"description": "Title of the documentation.",
Expand Down Expand Up @@ -100,8 +105,7 @@
},
"includesName": {
"description": "Name of item menu of externals markdown files.",
"type": "string",
"default": "Additional documentation"
"type": "string"
},

"disableCoverage": {
Expand Down

0 comments on commit 3ab6578

Please sign in to comment.