feat(docs-infra): generate Angular CLI command reference (#25363)
PR Close #25363
This commit is contained in:
Pete Bacon Darwin
Kara Erickson
parent
39a67548ac
commit
f29b218060
|
|
@ -0,0 +1 @@
|
|||
yarn.lock
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"dependencies": {
|
||||
"@angular/cli": "https://github.com/angular/cli-builds#master"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
<h1 class="no-toc">CLI Command Reference</h1>
|
||||
|
||||
The Angular CLI is a command-line tool that you use to initialize, develop, scaffold, and maintain Angular applications.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Installing Angular CLI
|
||||
|
||||
The current version of Angular CLI is 6.x.
|
||||
|
||||
* Both the CLI and the projects that you generate with the tool have dependencies that require Node 8.9 or higher, together with NPM 5.5.1 or higher.
|
||||
* Install the CLI using npm:
|
||||
`npm install -g @angular/cli`
|
||||
* The CLI is an open-source tool:
|
||||
https://github.com/angular/angular-cli/tree/master/packages/angular/cli
|
||||
|
||||
For details about changes between versions, and information about updating from previous releases, see the Releases tab on GitHub.
|
||||
|
||||
### Basic workflow
|
||||
|
||||
Invoke the tool on the command line through the ng executable. Online help is available on the command line:
|
||||
|
||||
```
|
||||
> ng help Lists commands with short descriptions
|
||||
> ng <command> --help Lists options for a command.
|
||||
```
|
||||
|
||||
To create, build, and serve a new, basic Angular project on a development server, use the following commands:
|
||||
|
||||
```
|
||||
cd <parent of new workspace>
|
||||
ng new my-project
|
||||
cd my-project
|
||||
ng serve
|
||||
```
|
||||
|
||||
In your browser, open http://localhost:4200/ to see the new app run.
|
||||
|
||||
### Workspaces and project files
|
||||
|
||||
Angular 6 introduced the workspace directory structure for Angular apps. A workspace defines a project. A project can contain multiple apps, as well as libraries that can be used in any of the apps.
|
||||
|
||||
Some commands (such as build) must be executed from within a workspace folder, and others (such as new) must be executed from outside any workspace. This requirement is called out in the description of each command where it applies.The `new` command creates a [workspace](guide/glossary#workspace) to contain [projects](guide/glossary#project). A project can be an app or a library, and a workspace can contain multiple apps and libraries.
|
||||
|
||||
A newly generated app project contains the source files for a root module, with a root component and template, which you can edit directly, or add to and modify using CLI commands. Use the generate command to add new files for additional components and services, and code for new pipes, directives, and so on.
|
||||
|
||||
* Commands such as `add` and `generate`, that create or operate on apps and libraries, must be executed from within a workspace folder.
|
||||
* Apps in a workspace can use libraries in the same workspace.
|
||||
* Each project has a `src` folder that contains the logic, data, and assets.
|
||||
See an example of the [file structure](guide/quickstart#project-file-review) in [Getting Started](guide/quickstart).
|
||||
|
||||
When you use the `serve` command to build an app, the server automatically rebuilds the app and reloads the page when you change any of the source files.
|
||||
|
||||
### Configuring the CLI
|
||||
|
||||
Configuration files let you customize your project. The CLI configuration file, angular.json, is created at the top level of the project folder. This is where you can set CLI defaults for your project, and specify which files to include when the CLI builds the project.
|
||||
|
||||
The CLI config command lets you set and retrieve configuration values from the command line, or you can edit the angular.json file directly.
|
||||
|
||||
* See the complete schema for angular.json.
|
||||
* Learn more about configuration options for Angular (link to new guide?)
|
||||
|
||||
### Command options and arguments
|
||||
|
||||
All commands and some options have aliases, as listed in the descriptions. Option names are prefixed with a double dash (--), but arguments and option aliases are not.
|
||||
|
||||
Typically, the name of a generated artifact can be given as an argument to the command or specified with the --name option. Most commands have additional options.
|
||||
|
||||
Command syntax is shown as follows:
|
||||
|
||||
```
|
||||
ng commandNameOrAlias <arg> [options]
|
||||
```
|
||||
|
||||
Options take either string or Boolean arguments. Defaults are shown in bold for Boolean or enumerated values, and are given with the description. For example:
|
||||
|
||||
```
|
||||
--optionNameOrAlias=<filename>
|
||||
--optionNameOrAlias=true|false
|
||||
--optionNameOrAlias=allowedValue1|allowedValue2|allowedValue3
|
||||
```
|
||||
|
||||
Boolean options can also be expressed with a prefix `no-` to indicate a value of false. For example, `--no-prod` is equivalent to `--prod=false`.
|
||||
|
|
@ -592,6 +592,17 @@
|
|||
"tooltip": "Details of the Angular classes and values.",
|
||||
"url": "api"
|
||||
},
|
||||
{
|
||||
"title": "CLI Commands",
|
||||
"tooltip": "Angular CLI command reference.",
|
||||
"children": [
|
||||
{
|
||||
"title": "Using the CLI",
|
||||
"tooltip": "An overview of how to use the CLI tool",
|
||||
"url": "cli"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"url": "guide/change-log",
|
||||
"title": "Change Log",
|
||||
|
|
|
|||
|
|
@ -18,13 +18,14 @@
|
|||
"build-for": "yarn ~~build --configuration",
|
||||
"prebuild-local": "yarn setup-local",
|
||||
"build-local": "yarn ~~build --configuration=stable",
|
||||
"extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js",
|
||||
"lint": "yarn check-env && yarn docs-lint && ng lint && yarn example-lint && yarn tools-lint",
|
||||
"test": "yarn check-env && ng test",
|
||||
"pree2e": "yarn check-env && yarn update-webdriver",
|
||||
"e2e": "ng e2e --no-webdriver-update",
|
||||
"presetup": "yarn --cwd .. install && yarn install --frozen-lockfile && yarn ~~check-env && yarn ~~clean-generated && yarn boilerplate:remove",
|
||||
"setup": "yarn aio-use-npm && yarn example-use-npm",
|
||||
"postsetup": "yarn boilerplate:add && yarn build-ie-polyfills && yarn docs",
|
||||
"postsetup": "yarn boilerplate:add && yarn build-ie-polyfills && yarn extract-cli-command-docs && yarn docs",
|
||||
"presetup-local": "yarn presetup",
|
||||
"setup-local": "yarn aio-use-local && yarn example-use-local",
|
||||
"postsetup-local": "yarn postsetup",
|
||||
|
|
@ -127,6 +128,8 @@
|
|||
"jasmine-spec-reporter": "^4.1.0",
|
||||
"jasmine-ts": "^0.2.1",
|
||||
"jsdom": "^9.12.0",
|
||||
"json-schema-traverse": "^0.4.1",
|
||||
"json5": "^1.0.1",
|
||||
"karma": "^1.7.0",
|
||||
"karma-chrome-launcher": "^2.1.1",
|
||||
"karma-cli": "^1.0.1",
|
||||
|
|
|
|||
|
|
@ -95,8 +95,11 @@ export class NavigationService {
|
|||
this.location.currentPath,
|
||||
|
||||
(navMap, url) => {
|
||||
const urlKey = url.startsWith('api/') ? 'api' : url;
|
||||
return navMap.get(urlKey) || { '' : { view: '', url: urlKey, nodes: [] }};
|
||||
const matchSpecialUrls = /^api|^cli/.exec(url);
|
||||
if (matchSpecialUrls) {
|
||||
url = matchSpecialUrls[0];
|
||||
}
|
||||
return navMap.get(url) || { '' : { view: '', url: url, nodes: [] }};
|
||||
})
|
||||
.pipe(publishReplay(1));
|
||||
(currentNodes as ConnectableObservable<CurrentNodes>).connect();
|
||||
|
|
|
|||
|
|
@ -135,17 +135,6 @@ th {
|
|||
text-align: left;
|
||||
}
|
||||
|
||||
p > code, li > code, td > code, th > code {
|
||||
font-family: $code-font;
|
||||
font-size: 85%;
|
||||
color: $darkgray;
|
||||
letter-spacing: 0;
|
||||
line-height: 1;
|
||||
padding: 2px 0;
|
||||
background-color: $backgroundgray;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: $code-font;
|
||||
font-size: 90%;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
.cli-name, .cli-default {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.cli-option-syntax {
|
||||
white-space: pre;
|
||||
}
|
||||
|
|
@ -8,6 +8,7 @@
|
|||
@import 'buttons';
|
||||
@import 'callout';
|
||||
@import 'card';
|
||||
@import 'cli-pages';
|
||||
@import 'code';
|
||||
@import 'contribute';
|
||||
@import 'contributor';
|
||||
|
|
|
|||
|
|
@ -9,11 +9,12 @@ const Package = require('dgeni').Package;
|
|||
const gitPackage = require('dgeni-packages/git');
|
||||
const apiPackage = require('../angular-api-package');
|
||||
const contentPackage = require('../angular-content-package');
|
||||
const cliDocsPackage = require('../cli-docs-package');
|
||||
const { extname, resolve } = require('canonical-path');
|
||||
const { existsSync } = require('fs');
|
||||
const { SRC_PATH } = require('../config');
|
||||
|
||||
module.exports = new Package('angular.io', [gitPackage, apiPackage, contentPackage])
|
||||
module.exports = new Package('angular.io', [gitPackage, apiPackage, contentPackage, cliDocsPackage])
|
||||
|
||||
// This processor relies upon the versionInfo. See below...
|
||||
.processor(require('./processors/processNavigationMap'))
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
const shelljs = require('shelljs');
|
||||
const {resolve} = require('canonical-path');
|
||||
const {CONTENTS_PATH} = require('../config');
|
||||
|
||||
shelljs.cd(resolve(CONTENTS_PATH, 'cli-src'));
|
||||
shelljs.exec('git clean -Xfd');
|
||||
shelljs.exec('yarn install');
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
const {resolve} = require('canonical-path');
|
||||
const Package = require('dgeni').Package;
|
||||
const basePackage = require('../angular-base-package');
|
||||
const contentPackage = require('../content-package');
|
||||
const {CONTENTS_PATH, TEMPLATES_PATH, requireFolder} = require('../config');
|
||||
|
||||
|
||||
// Define the dgeni package for generating the docs
|
||||
module.exports = new Package('cli-docs', [basePackage, contentPackage])
|
||||
|
||||
// Register the services and file readers
|
||||
.factory(require('./readers/cli-command'))
|
||||
|
||||
// Register the processors
|
||||
.processor(require('./processors/processCliContainerDoc'))
|
||||
.processor(require('./processors/processCliCommands'))
|
||||
.processor(require('./processors/filterHiddenCommands'))
|
||||
|
||||
// Configure file reading
|
||||
.config(function(readFilesProcessor, cliCommandFileReader) {
|
||||
const CLI_SOURCE_PATH = resolve(CONTENTS_PATH, 'cli-src/node_modules/@angular/cli/help');
|
||||
readFilesProcessor.fileReaders.push(cliCommandFileReader);
|
||||
readFilesProcessor.sourceFiles = readFilesProcessor.sourceFiles.concat([
|
||||
{
|
||||
basePath: CLI_SOURCE_PATH,
|
||||
include: resolve(CLI_SOURCE_PATH, '*.json'),
|
||||
fileReader: 'cliCommandFileReader'
|
||||
},
|
||||
{
|
||||
basePath: CONTENTS_PATH,
|
||||
include: resolve(CONTENTS_PATH, 'cli/**'),
|
||||
fileReader: 'contentFileReader'
|
||||
},
|
||||
]);
|
||||
})
|
||||
|
||||
.config(function(templateFinder, templateEngine, getInjectables) {
|
||||
// Where to find the templates for the CLI doc rendering
|
||||
templateFinder.templateFolders.unshift(resolve(TEMPLATES_PATH, 'cli'));
|
||||
// Add in templating filters and tags
|
||||
templateEngine.filters = templateEngine.filters.concat(getInjectables(requireFolder(__dirname, './rendering')));
|
||||
})
|
||||
|
||||
|
||||
.config(function(convertToJsonProcessor, postProcessHtml) {
|
||||
convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(['cli-command', 'cli-overview']);
|
||||
postProcessHtml.docTypes = postProcessHtml.docTypes.concat(['cli-command', 'cli-overview']);
|
||||
});
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
module.exports = function filterHiddenCommands() {
|
||||
return {
|
||||
$runAfter: ['files-read'],
|
||||
$runBefore: ['processCliContainerDoc'],
|
||||
$process(docs) {
|
||||
return docs.filter(doc => doc.docType !== 'cli-command' || doc.hidden !== true);
|
||||
}
|
||||
};
|
||||
};
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./filterHiddenCommands');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('filterHiddenCommands processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('cli-docs-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('filterHiddenCommands');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['files-read']);
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['processCliContainerDoc']);
|
||||
});
|
||||
|
||||
it('should remove CLI command docs that are hidden', () => {
|
||||
const processor = processorFactory();
|
||||
const filtered = processor.$process([
|
||||
{ docType: 'cli-command', id: 'one' },
|
||||
{ docType: 'cli-command', id: 'two', hidden: true },
|
||||
{ docType: 'cli-command', id: 'three', hidden: false },
|
||||
{ docType: 'other-doc', id: 'four', hidden: true },
|
||||
{ docType: 'other-doc', id: 'five', hidden: false },
|
||||
]);
|
||||
expect(filtered).toEqual([
|
||||
{ docType: 'cli-command', id: 'one' },
|
||||
{ docType: 'cli-command', id: 'three', hidden: false },
|
||||
{ docType: 'other-doc', id: 'four', hidden: true },
|
||||
{ docType: 'other-doc', id: 'five', hidden: false },
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
module.exports = function processCliCommands() {
|
||||
return {
|
||||
$runAfter: ['extra-docs-added'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
$process(docs) {
|
||||
const navigationDoc = docs.find(doc => doc.docType === 'navigation-json');
|
||||
const navigationNode = navigationDoc && navigationDoc.data['SideNav'].find(node => node.title === 'CLI Commands');
|
||||
|
||||
docs.forEach(doc => {
|
||||
if (doc.docType === 'cli-command') {
|
||||
doc.names = collectNames(doc.name, doc.commandAliases);
|
||||
|
||||
// Recursively process the options
|
||||
processOptions(doc, doc.options);
|
||||
|
||||
// Add to navigation doc
|
||||
if (navigationNode) {
|
||||
navigationNode.children.push({ url: doc.path, title: `ng ${doc.name}` });
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
function processOptions(container, options) {
|
||||
container.positionalOptions = [];
|
||||
container.namedOptions = [];
|
||||
|
||||
options.forEach(option => {
|
||||
|
||||
if (option.type === 'boolean' && option.default === undefined) {
|
||||
option.default = false;
|
||||
}
|
||||
|
||||
// Ignore any hidden options
|
||||
if (option.hidden) { return; }
|
||||
|
||||
option.types = option.types || [option.type];
|
||||
option.names = collectNames(option.name, option.aliases);
|
||||
|
||||
// Now work out what kind of option it is: positional/named
|
||||
if (option.positional !== undefined) {
|
||||
container.positionalOptions[option.positional] = option;
|
||||
} else {
|
||||
container.namedOptions.push(option);
|
||||
}
|
||||
|
||||
// Recurse if there are subcommands
|
||||
if (option.subcommands) {
|
||||
option.subcommands = getValues(option.subcommands);
|
||||
option.subcommands.forEach(subcommand => {
|
||||
subcommand.names = collectNames(subcommand.name, subcommand.aliases);
|
||||
processOptions(subcommand, subcommand.options);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
container.namedOptions.sort((a, b) => a.name > b.name ? 1 : -1);
|
||||
}
|
||||
|
||||
function collectNames(name, aliases) {
|
||||
return [name].concat(aliases);
|
||||
}
|
||||
|
||||
function getValues(obj) {
|
||||
return Object.keys(obj).map(key => obj[key]);
|
||||
}
|
||||
|
|
@ -0,0 +1,264 @@
|
|||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./processCliCommands');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('processCliCommands processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('cli-docs-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('processCliCommands');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['extra-docs-added']);
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['rendering-docs']);
|
||||
});
|
||||
|
||||
it('should collect the names (name + aliases)', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: ['alias1', 'alias2'],
|
||||
options: [],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.names).toEqual(['name', 'alias1', 'alias2']);
|
||||
});
|
||||
|
||||
describe('options', () => {
|
||||
it('should remove the hidden options', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [
|
||||
{ name: 'option1' },
|
||||
{ name: 'option2', hidden: true },
|
||||
{ name: 'option3' },
|
||||
{ name: 'option4', hidden: true },
|
||||
],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'option1' }),
|
||||
jasmine.objectContaining({ name: 'option3' }),
|
||||
]);
|
||||
});
|
||||
|
||||
it('should collect the non-hidden positional and named options', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [
|
||||
{ name: 'named1' },
|
||||
{ name: 'positional1', positional: 0},
|
||||
{ name: 'named2', hidden: true },
|
||||
{ name: 'positional2', hidden: true, positional: 1},
|
||||
],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.positionalOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'positional1', positional: 0}),
|
||||
]);
|
||||
expect(doc.namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'named1' }),
|
||||
]);
|
||||
});
|
||||
|
||||
it('should sort the named options into order by name', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [
|
||||
{ name: 'c' },
|
||||
{ name: 'a' },
|
||||
{ name: 'b' },
|
||||
],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'a' }),
|
||||
jasmine.objectContaining({ name: 'b' }),
|
||||
jasmine.objectContaining({ name: 'c' }),
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('subcommands', () => {
|
||||
it('should convert subcommands hash into a collection', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [{
|
||||
name: 'supercommand',
|
||||
subcommands: {
|
||||
subcommand1: {
|
||||
name: 'subcommand1',
|
||||
options: [
|
||||
{ name: 'subcommand1-option1' },
|
||||
{ name: 'subcommand1-option2' },
|
||||
],
|
||||
},
|
||||
subcommand2: {
|
||||
name: 'subcommand2',
|
||||
options: [
|
||||
{ name: 'subcommand2-option1' },
|
||||
{ name: 'subcommand2-option2' },
|
||||
],
|
||||
}
|
||||
},
|
||||
}],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.options[0].subcommands).toEqual([
|
||||
jasmine.objectContaining({ name: 'subcommand1' }),
|
||||
jasmine.objectContaining({ name: 'subcommand2' }),
|
||||
]);
|
||||
});
|
||||
|
||||
it('should remove the hidden subcommand options', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [{
|
||||
name: 'supercommand',
|
||||
subcommands: {
|
||||
subcommand1: {
|
||||
name: 'subcommand1',
|
||||
options: [
|
||||
{ name: 'subcommand1-option1' },
|
||||
{ name: 'subcommand1-option2', hidden: true },
|
||||
],
|
||||
},
|
||||
subcommand2: {
|
||||
name: 'subcommand2',
|
||||
options: [
|
||||
{ name: 'subcommand2-option1', hidden: true },
|
||||
{ name: 'subcommand2-option2' },
|
||||
],
|
||||
}
|
||||
},
|
||||
}],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.options[0].subcommands[0].namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'subcommand1-option1' }),
|
||||
]);
|
||||
expect(doc.options[0].subcommands[1].namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'subcommand2-option2' }),
|
||||
]);
|
||||
});
|
||||
|
||||
it('should collect the non-hidden positional arguments and named options', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [{
|
||||
name: 'supercommand',
|
||||
subcommands: {
|
||||
subcommand1: {
|
||||
name: 'subcommand1',
|
||||
options: [
|
||||
{ name: 'subcommand1-option1' },
|
||||
{ name: 'subcommand1-option2', positional: 0 },
|
||||
],
|
||||
},
|
||||
subcommand2: {
|
||||
name: 'subcommand2',
|
||||
options: [
|
||||
{ name: 'subcommand2-option1', hidden: true },
|
||||
{ name: 'subcommand2-option2', hidden: true, positional: 1 },
|
||||
],
|
||||
}
|
||||
},
|
||||
}],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.options[0].subcommands[0].positionalOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'subcommand1-option2', positional: 0}),
|
||||
]);
|
||||
expect(doc.options[0].subcommands[0].namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'subcommand1-option1' }),
|
||||
]);
|
||||
|
||||
expect(doc.options[0].subcommands[1].positionalOptions).toEqual([]);
|
||||
expect(doc.options[0].subcommands[1].namedOptions).toEqual([]);
|
||||
});
|
||||
|
||||
it('should sort the named subcommand options into order by name', () => {
|
||||
const processor = processorFactory();
|
||||
const doc = {
|
||||
docType: 'cli-command',
|
||||
name: 'name',
|
||||
commandAliases: [],
|
||||
options: [{
|
||||
name: 'supercommand',
|
||||
subcommands: {
|
||||
subcommand1: {
|
||||
name: 'subcommand1',
|
||||
options: [
|
||||
{ name: 'c' },
|
||||
{ name: 'a' },
|
||||
{ name: 'b' },
|
||||
]
|
||||
}
|
||||
}
|
||||
}],
|
||||
};
|
||||
processor.$process([doc]);
|
||||
expect(doc.options[0].subcommands[0].namedOptions).toEqual([
|
||||
jasmine.objectContaining({ name: 'a' }),
|
||||
jasmine.objectContaining({ name: 'b' }),
|
||||
jasmine.objectContaining({ name: 'c' }),
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
it('should add the command to the CLI node in the navigation doc', () => {
|
||||
const processor = processorFactory();
|
||||
const command = {
|
||||
docType: 'cli-command',
|
||||
name: 'command1',
|
||||
commandAliases: ['alias1', 'alias2'],
|
||||
options: [],
|
||||
path: 'cli/command1',
|
||||
};
|
||||
const navigation = {
|
||||
docType: 'navigation-json',
|
||||
data: {
|
||||
SideNav: [
|
||||
{ url: 'some/page', title: 'Some Page' },
|
||||
{ url: 'cli', title: 'CLI Commands', children: [
|
||||
{ url: 'cli', title: 'Using the CLI' },
|
||||
]},
|
||||
{ url: 'other/page', title: 'Other Page' },
|
||||
]
|
||||
}
|
||||
};
|
||||
processor.$process([command, navigation]);
|
||||
expect(navigation.data.SideNav[1].title).toEqual('CLI Commands');
|
||||
expect(navigation.data.SideNav[1].children).toEqual([
|
||||
{ url: 'cli', title: 'Using the CLI' },
|
||||
{ url: 'cli/command1', title: 'ng command1' },
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
module.exports = function processCliContainerDoc() {
|
||||
return {
|
||||
$runAfter: ['extra-docs-added'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
$process(docs) {
|
||||
const cliDoc = docs.find(doc => doc.id === 'cli/index');
|
||||
cliDoc.id = 'cli-container';
|
||||
cliDoc.commands = docs.filter(doc => doc.docType === 'cli-command');
|
||||
}
|
||||
};
|
||||
};
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./processCliContainerDoc');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('processCliContainerDoc processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('cli-docs-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('processCliContainerDoc');
|
||||
expect(processor.$process).toBeDefined();
|
||||
});
|
||||
|
||||
it('should run after the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runAfter).toEqual(['extra-docs-added']);
|
||||
});
|
||||
|
||||
it('should run before the correct processor', () => {
|
||||
const processor = processorFactory();
|
||||
expect(processor.$runBefore).toEqual(['rendering-docs']);
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
/**
|
||||
* This file reader will pull the contents from a cli command json file
|
||||
*
|
||||
* The doc will initially have the form:
|
||||
* ```
|
||||
* {
|
||||
* startingLine: 1,
|
||||
* ...
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
module.exports = function cliCommandFileReader(log) {
|
||||
const json5 = require('json5');
|
||||
return {
|
||||
name: 'cliCommandFileReader',
|
||||
defaultPattern: /\.json$/,
|
||||
getDocs(fileInfo) {
|
||||
try {
|
||||
const doc = json5.parse(fileInfo.content);
|
||||
const name = fileInfo.baseName;
|
||||
const path = `cli/${name}`;
|
||||
// We return a single element array because content files only contain one document
|
||||
const result = Object.assign(doc, {
|
||||
content: doc.description,
|
||||
docType: 'cli-command',
|
||||
startingLine: 1,
|
||||
id: `cli-${doc.name}`,
|
||||
commandAliases: doc.aliases || [],
|
||||
aliases: computeAliases(doc),
|
||||
path,
|
||||
outputPath: `${path}.json`,
|
||||
breadCrumbs: [
|
||||
{ text: 'CLI', path: 'cli' },
|
||||
{ text: name, path },
|
||||
]
|
||||
});
|
||||
return [result];
|
||||
} catch (e) {
|
||||
log.warn(`Failed to read cli command file: "${fileInfo.relativePath}" - ${e.message}`);
|
||||
}
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
function computeAliases(doc) {
|
||||
return [doc.name].concat(doc.aliases || []).map(alias => `cli-${alias}`);
|
||||
}
|
||||
|
|
@ -0,0 +1,124 @@
|
|||
const cliCommandReaderFactory = require('./cli-command');
|
||||
const reader = cliCommandReaderFactory();
|
||||
|
||||
const content = `
|
||||
{
|
||||
"name": "add",
|
||||
"description": "Add support for a library to your project.",
|
||||
"longDescription": "Add support for a library in your project, for example adding \`@angular/pwa\` which would configure\\nyour project for PWA support.\\n",
|
||||
"hidden": false,
|
||||
"type": "custom",
|
||||
"options": [
|
||||
{
|
||||
"name": "collection",
|
||||
"description": "The package to be added.",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"aliases": [],
|
||||
"hidden": false,
|
||||
"positional": 0
|
||||
},
|
||||
{
|
||||
"name": "help",
|
||||
"description": "Shows a help message.",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"aliases": [],
|
||||
"hidden": false
|
||||
},
|
||||
{
|
||||
"name": "helpJson",
|
||||
"description": "Shows the metadata associated with each flags, in JSON format.",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"aliases": [],
|
||||
"hidden": false
|
||||
}
|
||||
],
|
||||
"aliases": ['a'],
|
||||
"scope": "in"
|
||||
}
|
||||
`;
|
||||
|
||||
const fileInfo = {content, baseName: 'add'};
|
||||
|
||||
describe('cli-command reader', () => {
|
||||
describe('getDocs', () => {
|
||||
it('should return an array containing a single doc', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs.length).toEqual(1);
|
||||
});
|
||||
|
||||
it('should return a cli-command doc', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0]).toEqual(jasmine.objectContaining({
|
||||
id: 'cli-add',
|
||||
docType: 'cli-command',
|
||||
}));
|
||||
});
|
||||
|
||||
it('should extract the name from the fileInfo', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].name).toEqual('add');
|
||||
});
|
||||
|
||||
it('should compute the id and aliases', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].id).toEqual('cli-add');
|
||||
expect(docs[0].aliases).toEqual(['cli-add', 'cli-a']);
|
||||
});
|
||||
|
||||
it('should compute the path and outputPath', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].path).toEqual('cli/add');
|
||||
expect(docs[0].outputPath).toEqual('cli/add.json');
|
||||
});
|
||||
|
||||
it('should compute the bread crumbs', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].breadCrumbs).toEqual([
|
||||
{ text: 'CLI', path: 'cli' },
|
||||
{ text: 'add', path: 'cli/add' },
|
||||
]);
|
||||
});
|
||||
|
||||
it('should start at line 1', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].startingLine).toEqual(1);
|
||||
});
|
||||
|
||||
it('should extract the short description into the content', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].content).toEqual('Add support for a library to your project.');
|
||||
});
|
||||
|
||||
it('should extract the long description', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].longDescription).toEqual('Add support for a library in your project, for example adding `@angular/pwa` which would configure\nyour project for PWA support.\n');
|
||||
});
|
||||
|
||||
it('should extract the command type', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].type).toEqual('custom');
|
||||
});
|
||||
|
||||
it('should extract the command scope', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].scope).toEqual('in');
|
||||
});
|
||||
|
||||
it('should extract the command aliases', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].commandAliases).toEqual(['a']);
|
||||
});
|
||||
|
||||
it('should extract the options', () => {
|
||||
const docs = reader.getDocs(fileInfo);
|
||||
expect(docs[0].options).toEqual([
|
||||
jasmine.objectContaining({ name: 'collection' }),
|
||||
jasmine.objectContaining({ name: 'help' }),
|
||||
jasmine.objectContaining({ name: 'helpJson' }),
|
||||
]);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
module.exports = function cliNegate() {
|
||||
return {
|
||||
name: 'cliNegate',
|
||||
process: function(str) { return 'no' + str.charAt(0).toUpperCase() + str.slice(1); }
|
||||
};
|
||||
};
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
var factory = require('./cliNegate');
|
||||
|
||||
describe('cliNegate filter', function() {
|
||||
var filter;
|
||||
|
||||
beforeEach(function() { filter = factory(); });
|
||||
|
||||
it('should be called "cliNegate"', function() { expect(filter.name).toEqual('cliNegate'); });
|
||||
|
||||
it('should make the first char uppercase and add `no` to the front', function() {
|
||||
expect(filter.process('abc')).toEqual('noAbc');
|
||||
});
|
||||
|
||||
it('should make leave the rest of the chars alone', function() {
|
||||
expect(filter.process('abCdE')).toEqual('noAbCdE');
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
{% import 'lib/cli.html' as cli %}
|
||||
|
||||
<article>
|
||||
{% include 'include/cli-breadcrumb.html' %}
|
||||
{% include 'include/cli-header.html' %}
|
||||
|
||||
<aio-toc class="embedded"></aio-toc>
|
||||
|
||||
<div class="cli-body">
|
||||
{$ doc.shortDescription | marked $}
|
||||
{$ doc.description | marked $}
|
||||
{$ cli.renderSyntax(doc) $}
|
||||
{$ cli.renderArguments(doc.positionalOptions, 2) $}
|
||||
{$ cli.renderNamedOptions(doc.namedOptions, 2) $}
|
||||
{$ cli.renderSubcommands(doc) $}
|
||||
{$ doc.longDescription | marked $}
|
||||
</div>
|
||||
</article>
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
<div class="content">
|
||||
{$ doc.description | marked $}
|
||||
</div>
|
||||
|
||||
<h2>Command Overview</h2>
|
||||
<table class="is-full-width list-table property-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Command</th>
|
||||
<th>Alias</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for command in doc.commands %}
|
||||
<tr>
|
||||
<td><a class="code-anchor" href="{$ command.path $}"><code>{$ command.name $}</code></a></td>
|
||||
<td>{% for alias in command.commandAliases %}<code>{$ alias $} </code>{% endfor %}</td>
|
||||
<td>{$ command.description | marked $}</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
{% set comma = joiner(',') %}
|
||||
{% set slash = joiner('/') %}
|
||||
|
||||
<div class="breadcrumb">
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context": "http://schema.org",
|
||||
"@type": "BreadcrumbList",
|
||||
"itemListElement": [
|
||||
{%- for crumb in doc.breadCrumbs %}{$ comma() $}
|
||||
{ "@type": "ListItem", "position": {$ loop.index $}, "item": { "@id": "https://angular.io/{$ crumb.path $}", "name": "{$ crumb.text $}" } }{% endfor %}
|
||||
]
|
||||
}
|
||||
</script>
|
||||
{% for crumb in doc.breadCrumbs %}{% if not loop.last %} {$ slash() $} {% if crumb.path %}<a href="{$ crumb.path $}">{$ crumb.text $}</a>{% else %}{$ crumb.text $}{% endif %}{% endif %}{% endfor %}
|
||||
</div>
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
|
||||
<header class="cli-header">
|
||||
<h1>ng {$ doc.name $}</h1>
|
||||
</header>
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
{% macro renderSyntax(container, prefix) -%}
|
||||
{% for name in container.names %}
|
||||
<code-example hideCopy="true" class="no-box api-heading">ng {%if prefix %}{$ prefix $} {% endif %}<span class="cli-name">{$ name $}</span>
|
||||
{%- for arg in container.positionalOptions %} <<var>{$ arg.name $}</var>>{% endfor %}
|
||||
{%- if container.namedOptions.length %} [<var>options</var>]{% endif -%}
|
||||
</code-example>
|
||||
{% endfor %}
|
||||
{% endmacro %}
|
||||
|
||||
{% macro renderArguments(arguments, level = 2) %}
|
||||
{% if arguments.length %}
|
||||
<h{$ level $} class="no-anchor">Arguments</h{$ level $}>
|
||||
<table class="is-full-width list-table property-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Argument</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for option in arguments %}
|
||||
<tr class="cli-option">
|
||||
<td><code>{$ option.name $}</code></td>
|
||||
<td>
|
||||
{$ option.description | marked $}
|
||||
{% if option.subcommands.length -%}
|
||||
<p>This option can take one of the following <a href="#{$ option.name $}-commands">sub-commands</a>:<p>
|
||||
<ul>
|
||||
{% for subcommand in option.subcommands %}
|
||||
<li><code><a class="code-anchor" href="#{$ subcommand.name $}-command">{$ subcommand.name $}</a></code></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{%- endif %}
|
||||
</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
{% endif %}
|
||||
{% endmacro %}
|
||||
|
||||
{% macro renderNamedOptions(options, level = 2) %}
|
||||
{% if options.length %}
|
||||
<h{$ level $} class="no-anchor">Options</h{$ level $}>
|
||||
<table class="is-full-width list-table property-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for option in options %}
|
||||
<tr class="cli-option">
|
||||
<td>
|
||||
{% for type in option.types -%}
|
||||
{% for alias in option.names -%}
|
||||
<code class="cli-option-syntax">{$ renderOption(option.name, alias, type, option.default, option.enum) $}</code>
|
||||
{% if not loop.last %}<br>{% endif %}
|
||||
{% endfor -%}
|
||||
{% if not loop.last %}<br>{% endif %}
|
||||
{% endfor -%}
|
||||
</td>
|
||||
<td>
|
||||
{$ option.description | marked $}
|
||||
</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
{% endif %}
|
||||
{% endmacro %}
|
||||
|
||||
{% macro bold(isBold, contents) -%}
|
||||
<span {% if isBold %}class="cli-default"{% endif %}>{$ contents $}</span>
|
||||
{%- endmacro -%}
|
||||
|
||||
{%- macro renderValues(values, default) -%}
|
||||
{% for value in values %}{$ bold(value==default, value) $}{% if not loop.last %}|{% endif %}{% endfor %}
|
||||
{%- endmacro -%}
|
||||
|
||||
{%- macro renderOption(name, alias, type, default, values) -%}
|
||||
{% set prefix = '--' if (name === alias and name.length > 1) else '-' %}
|
||||
{%- if type === 'boolean' -%}
|
||||
{%- if not values.length %}{$ prefix $}{$ alias $}={$ renderValues([true, false], default) $}
|
||||
{% endif -%}
|
||||
{$ prefix $}{$ bold(default, alias) $}|{$ prefix $}{$ bold(not default, alias | cliNegate) $}
|
||||
{%- elif values.length -%}
|
||||
{$ prefix $}{$ alias $}={$ renderValues(values, default) $}
|
||||
{%- elif type === 'string' -%}
|
||||
{$ prefix $}{$ alias $}=<var>{$ name $}</var>
|
||||
{%- else -%}
|
||||
{$ prefix $}{$ alias $}
|
||||
{%- endif -%}
|
||||
{%- endmacro -%}
|
||||
|
||||
{%- macro renderSubcommands(container) -%}
|
||||
{% for command in container.positionalOptions %}{% if command.subcommands.length %}
|
||||
<h2><a id="{$ command.name $}-commands"></a>{$ command.name | title $} commands</h2>
|
||||
{% for subcommand in command.subcommands %}
|
||||
<h3><code><a id="{$ subcommand.name $}-command"></a>{$ subcommand.name $}</code></h3>
|
||||
{% for name in container.names %}
|
||||
{$ renderSyntax(subcommand, name) $}
|
||||
{% endfor %}
|
||||
{$ subcommand.description | marked $}
|
||||
{# for now we assume that commands do not have further sub-commands #}
|
||||
{$ renderArguments(subcommand.positionalOptions, 4) $}
|
||||
{$ renderNamedOptions(subcommand.namedOptions, 4) $}
|
||||
{% endfor %}
|
||||
{% endif %}{% endfor %}
|
||||
{%- endmacro -%}
|
||||
|
|
@ -6102,6 +6102,10 @@ json-schema-traverse@^0.3.0:
|
|||
version "0.3.1"
|
||||
resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-0.3.1.tgz#349a6d44c53a51de89b40805c5d5e59b417d3340"
|
||||
|
||||
json-schema-traverse@^0.4.1:
|
||||
version "0.4.1"
|
||||
resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz#69f6a87d9513ab8bb8fe63bdb0979c448e684660"
|
||||
|
||||
json-schema@0.2.3:
|
||||
version "0.2.3"
|
||||
resolved "https://registry.yarnpkg.com/json-schema/-/json-schema-0.2.3.tgz#b480c892e59a2f05954ce727bd3f2a4e882f9e13"
|
||||
|
|
@ -6124,6 +6128,12 @@ json5@^0.5.0, json5@^0.5.1:
|
|||
version "0.5.1"
|
||||
resolved "https://registry.yarnpkg.com/json5/-/json5-0.5.1.tgz#1eade7acc012034ad84e2396767ead9fa5495821"
|
||||
|
||||
json5@^1.0.1:
|
||||
version "1.0.1"
|
||||
resolved "https://registry.yarnpkg.com/json5/-/json5-1.0.1.tgz#779fb0018604fa854eacbf6252180d83543e3dbe"
|
||||
dependencies:
|
||||
minimist "^1.2.0"
|
||||
|
||||
jsonfile@^2.1.0:
|
||||
version "2.4.0"
|
||||
resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-2.4.0.tgz#3736a2b428b87bbda0cc83b53fa3d633a35c2ae8"
|
||||
|
|
|
|||
Loading…
Reference in New Issue