From f098ba080d9fa23545f1b1e90f76a8638e1efe2f Mon Sep 17 00:00:00 2001 From: Riva Junior Date: Wed, 17 May 2023 20:20:50 -0300 Subject: [PATCH] Docs improvements (#777) * docs: Update README.md - fix headings level - specify language on a fenced code block - add sub-levels on Input and output files - remove extra space after two list marks - fix typo * docs: remove trailing punctuation in one heading --- CONTRIBUTING.md | 2 +- README.md | 158 ++++++++++++++++++++++++------------------------ 2 files changed, 81 insertions(+), 79 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbb86979b..1bd9cf76b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,7 +44,7 @@ npm test npm test watch ``` -### Testing environment variables: +### Testing environment variables - `TEST_TIMEOUT`: Default millisecond timeout for test cases. - `SHOW_TEST_OUTPUT`: Set to show all `stdout` and `stderr` from spawned wireit diff --git a/README.md b/README.md index 8719f560d..d8c29bb33 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,8 @@ _Wireit upgrades your npm scripts to make them smarter and more efficient._ - [Parallelism](#parallelism) - [Extra arguments](#extra-arguments) - [Input and output files](#input-and-output-files) + - [Example configuration](#example-configuration) + - [Default excluded paths](#default-excluded-paths) - [Incremental build](#incremental-build) - [Caching](#caching) - [Local caching](#local-caching) @@ -119,7 +121,7 @@ If you use VSCode, consider installing the `google.wireit` extension. It adds do Install it [from the marketplace](https://marketplace.visualstudio.com/items?itemName=google.wireit) or on the command line like: -``` +```sh code --install-extension google.wireit ``` @@ -253,7 +255,7 @@ Setting these properties allow you to use more features of Wireit: | [**Incremental build**](#incremental-build) | ☑️ | ☑️ | | [**Caching**](#caching) | ☑️ | ☑️ | -#### Example configuration +### Example configuration ```json { @@ -277,7 +279,7 @@ Setting these properties allow you to use more features of Wireit: } ``` -#### Default excluded paths +### Default excluded paths By default, the following folders are excluded from the `files` and `output` arrays: @@ -599,81 +601,81 @@ an object, and setting the `cascade` property to `false`: There are two main reasons you might want to set `cascade` to `false`: -1. **Your script only consumes a subset of a dependency's output.** - - For example, `tsc` produces both `.js` files and `.d.ts` files, but only the - `.js` files might be consumed by `rollup`. There is no need to re-bundle - when a typings-only changed occured. - - > **Note** - > In addition to setting `cascade` to `false`, the subset of output that - > _does_ matter (`lib/**/*.js`) has been added to the `files` array. - - ```json - { - "scripts": { - "build": "wireit", - "bundle": "wireit" - }, - "wireit": { - "build": { - "command": "tsc", - "files": ["src/**/*.ts", "tsconfig.json"], - "output": ["lib/**"] - }, - "bundle": { - "command": "rollup -c", - "dependencies": [ - { - "script": "build", - "cascade": false - } - ], - "files": ["rollup.config.json", "lib/**/*.js"], - "output": ["dist/bundle.js"] - } - } - } - ``` - -2. **Your server doesn't need to restart for certain changes.** - - For example, a web server depends on some static assets, but the server - reads those assets from disk dynamically on each request. In [`watch`](#watch-mode) mode, - there is no need to restart the server when the assets change. - - > **Note** - > The `build:server` dependency uses the default `cascade` behavior - > (`true`), because changing the implementation of the server itself _does_ - > require the server to be restarted. - - ```json - { - "scripts": { - "start": "wireit", - "build:server": "wireit" - }, - "wireit": { - "start": { - "command": "node lib/server.js", - "service": true, - "dependencies": [ - "build:server", - { - "script": "../assets:build", - "cascade": false - } - ], - "files": ["lib/**/*.js"] - }, - "build:server": { - "command": "tsc", - "files": ["src/**/*.ts", "tsconfig.json"], - "output": ["lib/**"] - } - } - } - ``` +1. **Your script only consumes a subset of a dependency's output.** + + For example, `tsc` produces both `.js` files and `.d.ts` files, but only the + `.js` files might be consumed by `rollup`. There is no need to re-bundle + when a typings-only changed occurred. + + > **Note** + > In addition to setting `cascade` to `false`, the subset of output that + > _does_ matter (`lib/**/*.js`) has been added to the `files` array. + + ```json + { + "scripts": { + "build": "wireit", + "bundle": "wireit" + }, + "wireit": { + "build": { + "command": "tsc", + "files": ["src/**/*.ts", "tsconfig.json"], + "output": ["lib/**"] + }, + "bundle": { + "command": "rollup -c", + "dependencies": [ + { + "script": "build", + "cascade": false + } + ], + "files": ["rollup.config.json", "lib/**/*.js"], + "output": ["dist/bundle.js"] + } + } + } + ``` + +2. **Your server doesn't need to restart for certain changes.** + + For example, a web server depends on some static assets, but the server + reads those assets from disk dynamically on each request. In [`watch`](#watch-mode) mode, + there is no need to restart the server when the assets change. + + > **Note** + > The `build:server` dependency uses the default `cascade` behavior + > (`true`), because changing the implementation of the server itself _does_ + > require the server to be restarted. + + ```json + { + "scripts": { + "start": "wireit", + "build:server": "wireit" + }, + "wireit": { + "start": { + "command": "node lib/server.js", + "service": true, + "dependencies": [ + "build:server", + { + "script": "../assets:build", + "cascade": false + } + ], + "files": ["lib/**/*.js"] + }, + "build:server": { + "command": "tsc", + "files": ["src/**/*.ts", "tsconfig.json"], + "output": ["lib/**"] + } + } + } + ``` ## Failures and errors