Skip to content

Commit b9af53a

Browse files
author
nickpape-msft
authored
Merge pull request microsoft#3 from Microsoft/nickpape/improve-readme
Improve README
2 parents 41d53c3 + 44ea885 commit b9af53a

6 files changed

Lines changed: 302 additions & 117 deletions

File tree

‎BUILDING.md‎

Whitespace-only changes.

‎gulp-core-build-karma/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,40 @@
44

55
[![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-karma.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-karma)
66
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-karma.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-karma) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-karma.svg)](https://david-dm.org/Microsoft/gulp-core-build-karma)
7+
8+
# Description
9+
10+
**gulp-core-build-karma** is a gulp-core-build plugin which uses KarmaJS to configure a browser
11+
to run a bundle of code, primarily unit tests using mocha.
12+
13+
# KarmaTask
14+
## Usage
15+
16+
Simply register the task in a gulp-core-build tree, and it will automatically look for a **karma.config.js** file.
17+
The default karma config, which can be obtained by running the task with the `--initkarma` flag,
18+
always looks for a file called `src/tests.js` and uses this as the entry point for the bundle which will
19+
be tested.
20+
21+
The task will launch the PhantomJS browser and begin automatically running mocha tests.
22+
23+
Once testing is complete, a coverage report is written to the `coverage` folder.
24+
25+
A number of plugins for karma are automatically configured, including:
26+
* karma-webpack
27+
* karma-mocha
28+
* karma-coverage
29+
* karma-phantomjs-launcher
30+
* karma-sinon-chai
31+
32+
## Configuration
33+
34+
### karmaConfigPath
35+
36+
Sets the path to the Karma Configuration file to use. If one has not been created, this task
37+
will prompt the user to run it again with the `--initkarma` flag.
38+
39+
**Default:** './karma.config.json'
40+
41+
# License
42+
43+
MIT

‎gulp-core-build-mocha/README.md‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,48 @@
11
# gulp-core-build-mocha
22

3-
`gulp-core-build-mocha` is a `gulp-core-build` subtask for running unit tests using mocha/chai. This setup is useful for unit testing build tools, as it runs in the node process rather than in a browser.
3+
`gulp-core-build-mocha` is a `gulp-core-build` subtask for running unit tests and creating coverage reports using mocha/chai.
4+
This setup is useful for unit testing build tools, as it runs in the node process rather than in a browser.
45

56
[![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-mocha.svg)](https://badge.fury.io/js/gulp-core-build-mocha)
67
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-mocha.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-mocha) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-mocha.svg)](https://david-dm.org/Microsoft/gulp-core-build-mocha)
8+
9+
# Description
10+
11+
**gulp-core-build-mocha** is a gulp-core-build plugin which will automatically execute a set of
12+
unit test files using the mocha test suite.
13+
14+
# MochaTask
15+
## Usage
16+
17+
Simply create a file which ends in `.test.js`. Next, register the Mocha task to gulp-core-build.
18+
19+
A coverage report is both written to the console and to a folder on disk.
20+
21+
## Configuration
22+
23+
### testMatch
24+
25+
Sets the glob pattern which is used to locate the files to run tests on.
26+
27+
**Default:** 'lib/\*\*/\*.test.js'
28+
29+
### reportDir
30+
31+
The folder in which to store the coverage reports.
32+
33+
**Default:** 'coverage'
34+
35+
# InstrumentTask
36+
## Usage
37+
38+
This task selects which files should be covered by the code coverage tool.
39+
40+
## Configuration
41+
### coverageMatch
42+
An array of globs which define which files should be included in code coverage reports.
43+
44+
**Default:** `['lib/**/*.js', '!lib/**/*.test.js']`
45+
46+
# License
47+
48+
MIT

‎gulp-core-build-sass/README.md‎

Lines changed: 34 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,40 @@
55
[![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-sass.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-sass)
66
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-sass.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-sass) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-sass.svg)](https://david-dm.org/Microsoft/gulp-core-build-sass)
77

8-
# Tasks
9-
## SassTask
8+
# SassTask
109

11-
### Description
10+
## Usage
1211
This task invokes `gulp-sass` to compile source SASS files into a CommonJS module which uses `load-themed-styles` to load styles onto the page. If the `libAmdFolder` is specified globally, this task will also output an AMD module. Various templates may be specified.
1312

14-
### Config
15-
```typescript
16-
interface ISassTaskConfig {
17-
sassMatch?: string[];
18-
commonModuleTemplate: string;
19-
amdModuleTemplate: string;
20-
}
21-
```
22-
* **
23-
24-
Usage (and defaults):
25-
```typescript
26-
sass.setConfig({
27-
sassMatch: [
28-
'src/**/*.scss'
29-
],
30-
commonModuleTemplate: "require('load-themed-styles').loadStyles(<%= content %>);",
31-
amdModuleTemplate: "define(['load-themed-styles'], function(loadStyles) { loadStyles.loadStyles(<%= content %>); });"
32-
});
33-
```
13+
## Config
14+
### preamble
15+
An optional parameter for text to include in the generated typescript file.
16+
17+
**Default:** `'/* tslint:disable */'`
18+
19+
### postamble
20+
An optional parameter for text to include at the end of the generated typescript file.
21+
22+
**Default:** `'/* tslint:enable */'`
23+
24+
### sassMatch
25+
An array of glob patterns for locating SASS files.
26+
27+
**Default:** `['src/**/*.scss']`
28+
29+
### useCSSModules
30+
If this option is specified, files ending with `.module.scss` extension will automatically
31+
generate a corresponding TypeScript file. All classes will be appended with a hash
32+
to help ensure uniqueness on a page. This file can be imported directly, and will
33+
contain an object describing the mangled class names.
34+
35+
**Default:** `false`
36+
37+
### dropCssFiles
38+
If this is false, then we do not create `.css` files in the `lib` directory.
39+
40+
**Default:** `false`
41+
42+
# License
43+
44+
MIT

‎gulp-core-build-serve/README.md‎

Lines changed: 70 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,103 @@
11
# @microsoft/gulp-core-build-serve
22

3+
34
`gulp-core-build-serve` is a `gulp-core-build` subtask for testing/serving web content on the localhost, and live reloading it when things change.
45

56
[![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-serve.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-serve)
67
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-serve.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-serve) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-serve.svg)](https://david-dm.org/Microsoft/gulp-core-build-serve)
78

8-
# Tasks
9-
## ServeTask
9+
# ServeTask
10+
A task which spins up two servers, one for serving files in the project, and another for
11+
mocking out an API server to run on a different port.
12+
13+
## Usage
14+
`--nobrowser` will stop the browser from automatically launching.
15+
16+
`--port X` will use X as the currently active port.
17+
18+
## Config
19+
### api
20+
This configuration has two options. If it is undefined, no API endpoint is created.
1021

11-
### Description
22+
Default: `undefined`
23+
24+
### port
25+
The port to run the API server on.
26+
27+
### entryPath
28+
The path to the API file. This file should export an object of the following interface:
1229

13-
### Config
1430
```typescript
15-
interface IServeTaskConfig {
16-
api?: {
17-
port: number,
18-
entryPath: string
19-
};
20-
https: boolean;
21-
initialPage: string;
22-
port: number;
23-
keyPath: string;
24-
certPath: string;
25-
pfxPath: string;
26-
tryCreateDevCertificate: boolean;
31+
interface IApiMap {
32+
[ route: string ]: Function;
2733
}
2834
```
29-
* **
3035

31-
Usage (and defaults):
32-
```typescript
33-
let build = require('gulp-core-build');
34-
let serve = require('gulp-core-build-serve');
35-
36-
build.task('serve', serve);
37-
38-
serve.setConfig({
39-
api: null,
40-
initialPage: '/index.html',
41-
port: 4321,
42-
https: false,
43-
tryCreateDevCertificate: false,
44-
keyPath: undefined,
45-
certPath: undefined,
46-
pfxPath: undefined
47-
}
48-
);
49-
```
36+
### initialPage
37+
The initial URL to load. This is ignored if the `--nobrowser` option is specified.
38+
39+
Default: `'/index.html'`
40+
41+
### port
42+
The port to serve on.
43+
44+
Default: `4321`
45+
46+
### https
47+
A boolean determining whether HTTPS mode should be turned on.
48+
49+
Default: `false`
5050

51-
## TrustCertTask
51+
### keyPath
52+
When the `https` option is `true`, this is the path to the HTTPS key
5253

53-
### Description
54-
This task gnerates and trusts a development certificate. The certificate is self-signed
54+
Default: `undefined`
55+
56+
### certPath
57+
Path to the HTTPS cert
58+
59+
Default: `undefined`
60+
61+
### pfxPath
62+
Path to the HTTPS PFX cert
63+
64+
Default: `undefined`
65+
66+
### tryCreateDevCertificate
67+
If true, when gulp-core-build-serve is initialized and a dev certificate doesn't already exist and hasn't been
68+
specified, attempt to generate one and trust it automatically.
69+
70+
Default: `false`
71+
72+
# ReloadTask
73+
## Usage
74+
If this task is configured, whenever it is triggered it will tell `gulp-connect` to reload the page.
75+
76+
## Config
77+
*This task doesn't have any configuration options.*
78+
79+
# TrustCertTask
80+
## Usage
81+
This task generates and trusts a development certificate. The certificate is self-signed
5582
and stored, along with its private key, in the user's home directory. On Windows, it's
5683
trusted as a root certification authority in the user certificate store. On macOS, it's
5784
trusted as a root cert in the keychain. On other platforms, the certificate is generated
5885
and signed, but the user must trust it manually. See ***Development Certificate*** below for
5986
more information.
6087

61-
### Config
62-
88+
## Config
6389
*This task doesn't have any configuration options.*
6490

65-
## UntrustCertTask
66-
67-
### Description
91+
# UntrustCertTask
92+
## Usage
6893
On Windows, this task removes the certificate with the expected serial number from the user's
6994
root certification authorities list. On macOS, it finds the SHA signature of the certificate
7095
with the expected serial number and then removes that certificate from the keychain. On
7196
other platforms, the user must untrust the certificate manually. On all platforms,
7297
the certificate and private key are deleted from the user's home directory. See
7398
***Development Certificate*** below for more information.
7499

75-
### Config
76-
100+
## Config
77101
*This task doesn't have any configuration options.*
78102

79103
# Development Certificate

0 commit comments

Comments
 (0)