From a1414877a148b102fb941dd59f5f12d66f0366f2 Mon Sep 17 00:00:00 2001 From: PhilKunz Date: Wed, 31 Aug 2016 16:10:01 +0200 Subject: [PATCH] update docs --- README.md | 130 +---------------------------------------------- docs/config.md | 80 +++++++++++++++++++++++++++++ docs/default.md | 8 +++ docs/examples.md | 13 +++++ docs/index.md | 130 +---------------------------------------------- docs/info.md | 14 +++++ docs/install.md | 18 +++++++ docs/summary.md | 8 +++ 8 files changed, 145 insertions(+), 256 deletions(-) create mode 100644 docs/config.md create mode 100644 docs/default.md create mode 100644 docs/examples.md create mode 100644 docs/info.md create mode 100644 docs/install.md create mode 100644 docs/summary.md diff --git a/README.md b/README.md index 1694d34..ea108e1 100644 --- a/README.md +++ b/README.md @@ -16,137 +16,11 @@ Write npm modules with TypeScript without hassle. TypeScript ready. Fully ES6. [![TypeScript](https://img.shields.io/badge/TypeScript-2.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/) [![node](https://img.shields.io/badge/node->=%206.x.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/) -## What is NPMTS? +## Introduction NPMTS is your friend when it comes to write, test, publish and document NPM modules written in TypeScript. By default NPMTS will **bundle declaration files**. As a result npm module **code completion in editors like Visual Studio Code** works. There is a docker image available that includes npmts to make CI a breeze: [hosttoday/ht-docker-node:npmts on Dockerhub](https://hub.docker.com/r/hosttoday/ht-docker-node/) -### Install -First install npmts globally, then install the npmts-g locally. - -> **npmts-g* checks if the global version of npmts suffices the modules requirements. -If not it installs npmts locally in the right version during npm install. - -```sh -npm install npmts -g # installs npmts globally -npm install npmts-g --save-dev # installs npmts-g checking tool as devDependency -``` - -Then add it to your package.json's script section to trigger a build: - -```json -"scripts": { - "test": "(npmts)" -} -``` - -### Default task execution order - -1. **Config:** Check config in ./npmextra.json (Check out [npmextra](https://www.npmjs.com/package/npmextra)) -1. **Clean:** Clean up from any previous builds (old js files) -1. **Check:** Check project for typings declaration in package.json, unused dependencies and missing dependencies -1. **Transpile:** Transpile TypeScript with **inline sourcemaps** and **declaration files** to ES target -1. **Documentation:** Create TypeDoc Documentation from TypeScript files -1. **Test:** Babelify ES6 to ES5 on the fly, instrumentalize ES5 JavaScript with istanbul and run tests with Mocha. - -### npmextra.json -the npmts section in npmextra.json can be used to configure npmts. - -**Default** ->Note: When you are using `"mode":"default"` it'll cause npmts to override any other settings you may have made except for tsOptions (ES target etc.) -with default behaviour. - -```json -{ - "npmts":{ - "mode":"default" - } -} -``` - -**Custom settings** -```json -{ - "mode":"custom", - "docs":false, - "test":true, - "npmts":{ - "ts":{ - "./customdir/*.ts":"./" - }, - "tsOptions":{ - "declaration":false, - "target":"ES6" - }, - "cli":true - } -} -``` - -| key | default value | description | -| --- | --- | --- | -| `"mode"` | `"default"` | "default" will do default stuff and override , "custom" only does what you specify | -| `"docs"` | `true` | create docs for your module | -| `"test"` | `true` | test your module | -| `"ts"` | `{"./ts/*.ts":"./","./test/test.ts":"./test/"}` | allows you to define multiple ts portions | -| `"tsOptions"` | `{"target":"ES5", "declaration":"true"}` | specify options for tsc | -| `"cli"` | "false" | some modules are designed to be used from cli. If set to true NPMTS will create a cli.js that wires you dist files up for cli use. | - -### TypeScript -by default npmts looks for `./ts/*.ts` and `./test/test.ts` that will compile to -`./dist/*.js` and `./test/test.js` - -Use commonjs module system for wiring up files. - -### Declaration files -**npmts** also creates declaration files like `./dist/index.d.ts` by default. -You can reference it in your package.json like this. - -```json -"main": "dist/index.js", -"typings": ".dist/index.d.ts", -``` - -This is in line with the latest TypeScript best practices. -You can then import plugins via the TypeScript `import` Syntax -and tsc will pick up the declaration file automatically. - -### TypeDoc -By default TypeDoc will create docs for your module in `./pages/api/` directory. -> Note: Use [npmpage](https://www.npmjs.com/package/npmpage) to build a website for the module. -It also allows you to integrate api docs with a gitbook located in `./docs/` - -## Some notes: -#### Typings for third party modules that do not bundle declaration files -NPMTS no longer supports typings.json. Instead use the new TypeScript 2.x approach to typings using the @types/ npm scope. - -#### Instrumentalize Code -npmts instrumentalizes (using istanbul) the created JavaScript code to create a coverage report. - -#### Tests -Any errors will be shown with reference to their originating source in TypeScript -thanks to autogenerated source maps. - -## Example Usage in modules: -* [gulp-browser](https://www.npmjs.com/package/gulp-browser) - -> We will add more options over time. - -## Tips and tricks: - -* Use [npmts-g](https://www.npmjs.com/package/npmts-g) to use globally installed npmts and install npmts locally if no global npmts is available. -* Use [npmpage](https://www.npmjs.com/package/npmpage) to create a webpage from coverage reports and TypeDoc for the module -* Use [hosttoday/ht-docker-node:npmts](https://hub.docker.com/r/hosttoday/ht-docker-node/) for speedy CI builds -* Use [npmdocker](https://www.npmjs.com/package/npmdocker) for running tests consistently with docker. - -## Future Scope: -* automatically manage badges in README -* manage tslint to enforce code best practices -* tear down any differences between local and CI environments by using brand new npmdocker - -## About the authors: -[![Project Phase](https://mediaserve.lossless.digital/lossless.com/img/createdby_github.svg)](https://lossless.com/) - -[![PayPal](https://img.shields.io/badge/Support%20us-PayPal-blue.svg)](https://paypal.me/lossless) +For further information read the docs. diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..f4545b8 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,80 @@ +# Configuration of NPMTS +npmts can be configured to your needs: + +### npmextra.json +the npmts section in npmextra.json can be used to configure npmts. + +**Default** +>Note: When you are using `"mode":"default"` it'll cause npmts to override any other settings you may have made except for tsOptions (ES target etc.) +with default behaviour. + +```json +{ + "npmts":{ + "mode":"default" + } +} +``` + +**Custom settings** +```json +{ + "mode":"custom", + "docs":false, + "test":true, + "npmts":{ + "ts":{ + "./customdir/*.ts":"./" + }, + "tsOptions":{ + "declaration":false, + "target":"ES6" + }, + "cli":true + } +} +``` + +| key | default value | description | +| --- | --- | --- | +| `"mode"` | `"default"` | "default" will do default stuff and override , "custom" only does what you specify | +| `"docs"` | `true` | create docs for your module | +| `"test"` | `true` | test your module | +| `"ts"` | `{"./ts/*.ts":"./","./test/test.ts":"./test/"}` | allows you to define multiple ts portions | +| `"tsOptions"` | `{"target":"ES5", "declaration":"true"}` | specify options for tsc | +| `"cli"` | "false" | some modules are designed to be used from cli. If set to true NPMTS will create a cli.js that wires you dist files up for cli use. | + +### TypeScript +by default npmts looks for `./ts/*.ts` and `./test/test.ts` that will compile to +`./dist/*.js` and `./test/test.js` + +Use commonjs module system for wiring up files. + +### Declaration files +**npmts** also creates declaration files like `./dist/index.d.ts` by default. +You can reference it in your package.json like this. + +```json +"main": "dist/index.js", +"typings": ".dist/index.d.ts", +``` + +This is in line with the latest TypeScript best practices. +You can then import plugins via the TypeScript `import` Syntax +and tsc will pick up the declaration file automatically. + +### TypeDoc +By default TypeDoc will create docs for your module in `./pages/api/` directory. +> Note: Use [npmpage](https://www.npmjs.com/package/npmpage) to build a website for the module. +It also allows you to integrate api docs with a gitbook located in `./docs/` + +## Some notes: +#### Typings for third party modules that do not bundle declaration files +NPMTS no longer supports typings.json. Instead use the new TypeScript 2.x approach to typings using the @types/ npm scope. + +#### Instrumentalize Code +npmts instrumentalizes (using istanbul) the created JavaScript code to create a coverage report. + +#### Tests +Any errors will be shown with reference to their originating source in TypeScript +thanks to autogenerated source maps. \ No newline at end of file diff --git a/docs/default.md b/docs/default.md new file mode 100644 index 0000000..9dd4b56 --- /dev/null +++ b/docs/default.md @@ -0,0 +1,8 @@ +### Default task execution order + +1. **Config:** Check config in ./npmextra.json (Check out [npmextra](https://www.npmjs.com/package/npmextra)) +1. **Clean:** Clean up from any previous builds (old js files) +1. **Check:** Check project for typings declaration in package.json, unused dependencies and missing dependencies +1. **Transpile:** Transpile TypeScript with **inline sourcemaps** and **declaration files** to ES target +1. **Documentation:** Create TypeDoc Documentation from TypeScript files +1. **Test:** Babelify ES6 to ES5 on the fly, instrumentalize ES5 JavaScript with istanbul and run tests with Mocha. \ No newline at end of file diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..d5a1e12 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,13 @@ +# Examples for NPMTS + +## Example Usage in modules: +* [gulp-browser](https://www.npmjs.com/package/gulp-browser) + +> We will add more options over time. + +## Tips and tricks: + +* Use [npmts-g](https://www.npmjs.com/package/npmts-g) to use globally installed npmts and install npmts locally if no global npmts is available. +* Use [npmpage](https://www.npmjs.com/package/npmpage) to create a webpage from coverage reports and TypeDoc for the module +* Use [hosttoday/ht-docker-node:npmts](https://hub.docker.com/r/hosttoday/ht-docker-node/) for speedy CI builds +* Use [npmdocker](https://www.npmjs.com/package/npmdocker) for running tests consistently with docker. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 1694d34..ea108e1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,137 +16,11 @@ Write npm modules with TypeScript without hassle. TypeScript ready. Fully ES6. [![TypeScript](https://img.shields.io/badge/TypeScript-2.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/) [![node](https://img.shields.io/badge/node->=%206.x.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/) -## What is NPMTS? +## Introduction NPMTS is your friend when it comes to write, test, publish and document NPM modules written in TypeScript. By default NPMTS will **bundle declaration files**. As a result npm module **code completion in editors like Visual Studio Code** works. There is a docker image available that includes npmts to make CI a breeze: [hosttoday/ht-docker-node:npmts on Dockerhub](https://hub.docker.com/r/hosttoday/ht-docker-node/) -### Install -First install npmts globally, then install the npmts-g locally. - -> **npmts-g* checks if the global version of npmts suffices the modules requirements. -If not it installs npmts locally in the right version during npm install. - -```sh -npm install npmts -g # installs npmts globally -npm install npmts-g --save-dev # installs npmts-g checking tool as devDependency -``` - -Then add it to your package.json's script section to trigger a build: - -```json -"scripts": { - "test": "(npmts)" -} -``` - -### Default task execution order - -1. **Config:** Check config in ./npmextra.json (Check out [npmextra](https://www.npmjs.com/package/npmextra)) -1. **Clean:** Clean up from any previous builds (old js files) -1. **Check:** Check project for typings declaration in package.json, unused dependencies and missing dependencies -1. **Transpile:** Transpile TypeScript with **inline sourcemaps** and **declaration files** to ES target -1. **Documentation:** Create TypeDoc Documentation from TypeScript files -1. **Test:** Babelify ES6 to ES5 on the fly, instrumentalize ES5 JavaScript with istanbul and run tests with Mocha. - -### npmextra.json -the npmts section in npmextra.json can be used to configure npmts. - -**Default** ->Note: When you are using `"mode":"default"` it'll cause npmts to override any other settings you may have made except for tsOptions (ES target etc.) -with default behaviour. - -```json -{ - "npmts":{ - "mode":"default" - } -} -``` - -**Custom settings** -```json -{ - "mode":"custom", - "docs":false, - "test":true, - "npmts":{ - "ts":{ - "./customdir/*.ts":"./" - }, - "tsOptions":{ - "declaration":false, - "target":"ES6" - }, - "cli":true - } -} -``` - -| key | default value | description | -| --- | --- | --- | -| `"mode"` | `"default"` | "default" will do default stuff and override , "custom" only does what you specify | -| `"docs"` | `true` | create docs for your module | -| `"test"` | `true` | test your module | -| `"ts"` | `{"./ts/*.ts":"./","./test/test.ts":"./test/"}` | allows you to define multiple ts portions | -| `"tsOptions"` | `{"target":"ES5", "declaration":"true"}` | specify options for tsc | -| `"cli"` | "false" | some modules are designed to be used from cli. If set to true NPMTS will create a cli.js that wires you dist files up for cli use. | - -### TypeScript -by default npmts looks for `./ts/*.ts` and `./test/test.ts` that will compile to -`./dist/*.js` and `./test/test.js` - -Use commonjs module system for wiring up files. - -### Declaration files -**npmts** also creates declaration files like `./dist/index.d.ts` by default. -You can reference it in your package.json like this. - -```json -"main": "dist/index.js", -"typings": ".dist/index.d.ts", -``` - -This is in line with the latest TypeScript best practices. -You can then import plugins via the TypeScript `import` Syntax -and tsc will pick up the declaration file automatically. - -### TypeDoc -By default TypeDoc will create docs for your module in `./pages/api/` directory. -> Note: Use [npmpage](https://www.npmjs.com/package/npmpage) to build a website for the module. -It also allows you to integrate api docs with a gitbook located in `./docs/` - -## Some notes: -#### Typings for third party modules that do not bundle declaration files -NPMTS no longer supports typings.json. Instead use the new TypeScript 2.x approach to typings using the @types/ npm scope. - -#### Instrumentalize Code -npmts instrumentalizes (using istanbul) the created JavaScript code to create a coverage report. - -#### Tests -Any errors will be shown with reference to their originating source in TypeScript -thanks to autogenerated source maps. - -## Example Usage in modules: -* [gulp-browser](https://www.npmjs.com/package/gulp-browser) - -> We will add more options over time. - -## Tips and tricks: - -* Use [npmts-g](https://www.npmjs.com/package/npmts-g) to use globally installed npmts and install npmts locally if no global npmts is available. -* Use [npmpage](https://www.npmjs.com/package/npmpage) to create a webpage from coverage reports and TypeDoc for the module -* Use [hosttoday/ht-docker-node:npmts](https://hub.docker.com/r/hosttoday/ht-docker-node/) for speedy CI builds -* Use [npmdocker](https://www.npmjs.com/package/npmdocker) for running tests consistently with docker. - -## Future Scope: -* automatically manage badges in README -* manage tslint to enforce code best practices -* tear down any differences between local and CI environments by using brand new npmdocker - -## About the authors: -[![Project Phase](https://mediaserve.lossless.digital/lossless.com/img/createdby_github.svg)](https://lossless.com/) - -[![PayPal](https://img.shields.io/badge/Support%20us-PayPal-blue.svg)](https://paypal.me/lossless) +For further information read the docs. diff --git a/docs/info.md b/docs/info.md new file mode 100644 index 0000000..0e64c7c --- /dev/null +++ b/docs/info.md @@ -0,0 +1,14 @@ +# Info + +## Future Scope: +* automatically manage badges in README +* manage tslint to enforce code best practices +* tear down any differences between local and CI environments by using brand new npmdocker + +## About the authors: +[![Project Phase](https://mediaserve.lossless.digital/lossless.com/img/createdby_github.svg)](https://lossless.com/) + +[![PayPal](https://img.shields.io/badge/Support%20us-PayPal-blue.svg)](https://paypal.me/lossless) + +## Legal Info +https://lossless.gmbh \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..5d16a16 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,18 @@ +# Install NPMTS +First install npmts globally, then install the npmts-g locally. + +> **npmts-g* checks if the global version of npmts suffices the modules requirements. +If not it installs npmts locally in the right version during npm install. + +```sh +npm install npmts -g # installs npmts globally +npm install npmts-g --save-dev # installs npmts-g checking tool as devDependency +``` + +Then add it to your package.json's script section to trigger a build: + +```json +"scripts": { + "test": "(npmts)" +} +``` \ No newline at end of file diff --git a/docs/summary.md b/docs/summary.md new file mode 100644 index 0000000..c7276cf --- /dev/null +++ b/docs/summary.md @@ -0,0 +1,8 @@ +# Summary + +* [Intro](index.md) +* [Install](install.md) +* [Default Behaviour](default.md) +* [Configuration](config.md) +* [Examples](examples.md) +* [Info](info.md) \ No newline at end of file