Refactor and de-duplicate documentation (palantir#2498)

- Removed a lot of documentation from the README that was duplicated in the Jekyll documentation site.
- Spruced up some existing markdown docs.

docs/_data/usage_sidebar.json

@@ -10,21 +10,25 @@
          "title": "Library",
          "url": "/library/"
       },
-      {
-         "title": "Third-Party Tools",
-         "url": "/third-party-tools/"
-      },
       {
          "title": "tslint.json",
          "url": "/tslint-json/"
       },
+      {
+         "title": "Rule Flags",
+         "url": "/rule-flags/"
+      },
+      {
+          "title": "Type Checking",
+          "url": "/type-checking/"
+      },
       {
          "title": "Custom Rules",
          "url": "/custom-rules/"
       },
       {
-         "title": "Rule Flags",
-         "url": "/rule-flags/"
+         "title": "Third-Party Tools",
+         "url": "/third-party-tools/"
       }
    ]
 }

docs/_includes/peer_dependencies.md

@@ -1,10 +1,6 @@
-##### Peer dependencies #####
+##### Peer dependencies
 
-The `typescript` module is a peer dependency of TSLint, which allows you to update the compiler independently from the
-linter. This also means that `tslint` will have to use the same version of `tsc` used to actually compile your sources.
+The `typescript` package is a peer dependency of TSLint. This allows you to update the compiler independently from the linter.
+This also means that `tslint` will have to use the same version of `tsc` which is used to actually compile your sources.
 
-Breaking changes in the latest dev release of `typescript@next` might break something in the linter if we haven't built against that release yet. If this happens to you, you can try:
-
-1. picking up `tslint@next`, which may have some bugfixes not released in `tslint@latest`
-   (see [release notes here](https://github.com/palantir/tslint/releases)).
-2. rolling back `typescript` to a known working version.
+Although the peer dependency allows installing the latest nightly releases of `typescript@next`, be aware that these might include breaking changes that cause the linter to malfunction.

docs/develop/custom-formatters/index.md

@@ -20,4 +20,4 @@ export class Formatter extends Lint.Formatters.AbstractFormatter {
 
 Such custom formatters can also be written in Javascript. Additionally, formatter files are always named with the suffix `Formatter`, and referenced from TSLint without its suffix.
 
-[0]: {{site.baseurl | append: "/develop/custom-rules"}}
+[0]: {{site.baseurl | append: "/develop/custom-rules"}}

docs/develop/custom-rules/index.md

@@ -3,6 +3,7 @@ title: Custom Rules
 layout: page
 permalink: "/develop/custom-rules/"
 ---
+
 TSLint ships with a set of core rules that can be configured. However, users are also allowed to write their own rules, which allows them to enforce specific behavior not covered by the core of TSLint. TSLint's internal rules are itself written to be pluggable, so adding a new rule is as simple as creating a new rule file named by convention. New rules can be written in either TypeScript or JavaScript; if written in TypeScript, the code must be compiled to JavaScript before invoking TSLint.
 
 Let us take the example of how to write a new rule to forbid all import statements (you know, *for science*). Let us name the rule file `noImportsRule.ts`. Rules are referenced in `tslint.json` with their kebab-cased identifer, so `"no-imports": true` would configure the rule.
@@ -44,8 +45,8 @@ Given a walker, TypeScript's parser visits the AST using the visitor pattern. So
 
 We still need to hook up this new rule to TSLint. First make sure to compile `noImportsRule.ts`:
 
-```bash
-tsc --noImplicitAny noImportsRule.ts
+```sh
+tsc noImportsRule.ts
 ```
 
 Then, if using the CLI, provide the directory that contains this rule as an option to `--rules-dir`. If using TSLint as a library or via `grunt-tslint`, the `options` hash must contain `"rulesDirectory": "..."`. If you run the linter, you'll see that we have now successfully banned all import statements via TSLint!
@@ -60,8 +61,7 @@ Instantiate a `Fix` object and pass it in as an argument to `addFailure`. This s
 
 ```typescript
 // create a fixer for this failure
-const replacement = new Lint.Replacement(node.getStart(), node.getWidth(), "");
-const fix = new Lint.Fix("no-imports", [replacement]);
+const fix = new Lint.Replacement(node.getStart(), node.getWidth(), "");
 
 // create a failure at the current position
 this.addFailure(this.createFailure(node.getStart(), node.getWidth(), Rule.FAILURE_STRING, fix));

docs/formatters/index.md

@@ -0,0 +1,16 @@
+---
+layout: page
+title: Formatters
+permalink: /formatters/
+menu: main
+order: 2
+---
+
+_Formatters_ allow for transformation of lint results into various forms before outputting to stdout or a file.
+
+### Built-in formatters
+
+{% assign formatters = site.data.formatters | sort: "name" %}
+{% for formatter in formatters %}
+* [{{formatter.formatterName}}]({{formatter.formatterName}})</a> - {{formatter.description | markdownify | remove:"<p>" | remove: "</p>"}}
+{% endfor %}

docs/index.md

@@ -3,36 +3,23 @@ title: TSLint
 layout: default
 subtitle: An extensible linter for the TypeScript language.
 ---
-TSLint checks your [TypeScript][0] code for readability, maintainability, and functionality errors.
 
-## Getting Started
+TSLint is a static analysis tool that checks your [TypeScript][0] code for readability, maintainability, and functionality errors. It is widely supported across modern editors & build systems and can be customized with your own lint rules, configurations, and formatters.
 
-#### Local installation
+## Quick start
 
 ```sh
-$ npm install tslint typescript --save-dev
-```
-
-#### Global installation
-
-```sh
-$ npm install tslint typescript -g
-```
-
-#### Configuration
+# Install the global CLI and its peer dependency
+yarn global add tslint typescript
 
-Generate a skeleton `tslint.json` config file with the `--init` CLI flag:
-
-```sh
+# Navigate to to your sources folder
 cd path/to/project
-tslint --init
-```
 
-Lint your TypeScript files!
+# Generate a basic configuration file
+tslint --init
 
-```
-// provide globs as strings
-tslint -c path/to/tslint.json 'path/to/project/**/*.ts'
+# Lint TypeScript source globs
+tslint -c tslint.json 'src/**/*.ts'
 ```
 
 Check out [the full usage guide][1] to learn more.

docs/rules/index.md

@@ -0,0 +1,33 @@
+---
+layout: page
+title: Rules
+permalink: /rules/
+menu: main
+order: 2
+---
+
+_Rules_ encode logic for syntactic & semantic checks of TypeScript source code.
+
+### TypeScript Specific
+
+_These rules find errors related to TypeScript features_:
+
+{% include rule_list.html ruleType="typescript" %}
+
+### Functionality
+
+_These rules catch common errors in JS programming or otherwise confusing constructs that are prone to producing bugs_:
+
+{% include rule_list.html ruleType="functionality" %}
+
+### Maintainability
+
+_These rules make code maintenance easier_:
+
+{% include rule_list.html ruleType="maintainability" %}
+
+### Style
+
+_These rules enforce consistent style across your codebase_:
+
+{% include rule_list.html ruleType="style" %}

docs/usage/cli/index.md

@@ -1,26 +1,30 @@
 ---
 title: CLI
 layout: page
-permalink: "/usage/cli/"
+permalink: /usage/cli/
 ---
+
 ### Installation
 
 __Local__ (in your project's working directory):
 
-```
-$ npm install tslint typescript --save-dev
+```sh
+npm install tslint typescript --save-dev
+# or
+yarn add tslint typescript
 ```
 
 __Global__:
 
+```sh
+npm install tslint typescript -g
+# or
+yarn global add tslint typescript
 ```
-$ npm install tslint typescript -g
-```
-
 
 {% include peer_dependencies.md %}
 
-### Usage ###
+### Usage
 
 Please ensure that the TypeScript source files compile correctly _before_ running the linter.
 
@@ -130,4 +134,12 @@ tslint accepts the following command-line options:
     Prints this help message.
 ```
 
+#### Exit Codes
+
+The CLI process may exit with the following codes:
+
+- `0`: Linting succeeded without errors (warnings may have ocurred)
+- `1`: An invalid command line argument or combination thereof was used
+- `2`: Linting failed with one or more rule violations with severity `error`
+
 [0]: {{site.baseurl | append: "/rules/"}}

docs/usage/configuration/index.md

@@ -0,0 +1,90 @@
+---
+layout: page
+title: Configuration
+permalink: /usage/configuration/
+---
+
+### tslint.json
+
+When using [the CLI][0] or many [third-party tools][1], a file named `tslint.json` is used to
+configure which rules get run and each of their options. This configuration file may be comp
+
+`tslint.json` files can have the following fields specified:
+
+* `extends?: string | string[]`:
+The name of a built-in configuration preset (see built-in presets below), or a path or
+array of paths to other configuration files which are extended by this configuration.
+This value is handled using node module resolution semantics.
+For example, a value of `"tslint-config"` would tell TSLint to try and load the main file of a module
+named "tslint-config" as a configuration file. Specific files inside node modules can also be
+specified, eg. `"tslint-config/path/to/submodule"`. Relative paths to JSON files or JS modules
+are also supported, e.g. `"./tslint-config"`.
+* `rulesDirectory?: string | string[]`:
+A path or array of paths to a directories of [custom rules][2]. These may be relative or absolute paths.
+* `rules?: { [name: string]: RuleSetting }`: A map of rule names to their configuration settings.
+  - These rules are applied to `.ts` and `.tsx` files.
+  - Each rule is associated with an object containing:
+    - `options?: any`: An array of values that are specific to a rule.
+    - `severity?: "default" | "error" | "warning" | "off"`: Severity level. Level "error" will cause exit code 2.
+  - A boolean value may be specified instead of the above object, and is equivalent to setting no options with default severity.
+  - Any rules specified in this block will override those configured in any base configuration being extended.
+  - [Check out the full rules list here][3].
+* `jsRules?: any`: Same format as `rules`. These rules are applied to `.js` and `.jsx` files.
+* `defaultSeverity?: "error" | "warning" | "off"`: The severity level used when a rule specifies a default warning level. If undefined, "error" is used. This value is not inherited and is only applied to rules in this file.
+
+`tslint.json` configuration files may have JavaScript-style `// single-line` and `/* multi-line */` comments in them (even though this is technically invalid JSON). If this confuses your syntax highlighter, you may want to switch it to JavaScript format.
+
+An example `tslint.json` file might look like this:
+
+```json
+{
+    "extends": "tslint:recommended",
+    "rulesDirectory": ["path/to/custom/rules/directory/", "another/path/"],
+    "rules": {
+        "max-line-length": {
+            "options": [120]
+        },
+        "new-parens": true,
+        "no-arg": true,
+        "no-bitwise": true,
+        "no-conditional-assignment": true,
+        "no-consecutive-blank-lines": false,
+        "no-console": {
+            "options": [
+                "debug",
+                "info",
+                "log",
+                "time",
+                "timeEnd",
+                "trace",
+            ]
+        }
+    },
+    "jsRules": {
+        "max-line-length": {
+            "options": [120]
+        }
+    }
+}
+```
+
+### Rule Severity
+
+The severity level of each rule can can be configured to `default`, `error`, `warning`/`warn`, or `off`/`none`. If no severity level is specified, `default` is used. The `defaultSeverity` top-level option replaces the severity level for each rule that uses severity level `default` in the current file. Valid values for `defaultSeverity` include `error`, `warning`/`warn`, and `off`/`none`.
+
+### Configuration presets
+
+TSLint ships with a handful of built-in configurations presets. You may inspect their source [here](https://github.com/palantir/tslint/tree/master/src/configs).
+
+__`tslint:recommended`__ is a stable, somewhat opinionated set of rules which we encourage for general TypeScript programming. This configuration follows semver, so it will _not_ have breaking changes across minor or patch releases.
+
+__`tslint:latest`__ extends `tslint:recommended` and is continuously updated to include configuration for the latest rules in every TSLint release. Using this config may introduce breaking changes across minor releases as new rules are enabled which cause lint failures in your code. When TSLint reaches a major version bump, `tslint:recommended` will be updated to be identical to `tslint:latest`.
+
+__`tslint:all`__ turns on all rules to their strictest settings. This will use type checking, so it must be combined with the `--project` option.
+(Exceptions are [`"ban"`](https://palantir.github.io/tslint/rules/ban/), [`"import-blacklist"`](https://palantir.github.io/tslint/rules/import-blacklist/), and [`"file-header"`](https://palantir.github.io/tslint/rules/file-header/), which have no sensible defaults, and deprecated rules.)
+
+
+[0]: {{site.baseurl | append: "/usage/cli"}}
+[1]: {{site.baseurl | append: "/usage/third-party-tools"}}
+[2]: {{site.baseurl | append: "/usage/custom-rules"}}
+[3]: {{site.baseurl | append: "/rules"}}

docs/usage/custom-rules/index.md

@@ -4,26 +4,10 @@ title: Custom Rules
 permalink: /usage/custom-rules/
 ---
 
-If we don't have all the rules you're looking for,
-you can either [write your own custom rules][0] or use custom rules that others have developed.
+If TSLint's core rules don't have all the lint checks you're looking for,
+you may [write your own custom rules][0] or use custom rules that others have developed.
 
-Then, when [using the CLI][1], point it to a directory with your compiled custom rules like the following:
-
-```
-tslint --rules-dir path/to/directory-with-rules/ file/to/lint.ts
-```
-
-You can do similarly when [using the library version][2] by specifying a `rulesDirectory` field of your `options` object. 
-
-Finally, you can specify the path to your custom rules inside of your [`tslint.json` file][3].
-
-#### Custom Rules from the TypeScript Community ####
-
- The repos below are good sources of community-created TSLint rules:
-
-- [ESLint rules for TSLint](https://github.com/buzinas/tslint-eslint-rules) - Improve your TSLint with the missing ESLint Rules
-- [tslint-microsoft-contrib](https://github.com/Microsoft/tslint-microsoft-contrib) - A set of TSLint rules used on some Microsoft projects
-- [ng2lint](https://github.com/mgechev/ng2lint) - A set of TSLint rules for static code analysis of Angular 2 TypeScript projects
+Review the [CLI][1] and [library][2] usage docs for configuring custom rule directories.
 
 [0]: {{site.baseurl | append: "/develop/custom-rules/"}}
 [1]: {{site.baseurl | append: "/usage/cli/"}}