docs: Formatters page updates (#16566)

bpmutter · mdjermanovic · web-flow · commit dfc7ec11b11b · 2022-12-06T16:54:56.000+01:00
* docs: Formatters page updates add more information about the built-in formatters Fixes #16476 * add formatter text generation * fix issue and rename manifest * fix manifest formatting issues * restore generated page to state of eslint/eslint:main * rename and refactor as json * fix template spacing * Apply suggestions from code review Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
diff --git a/Makefile.js b/Makefile.js
@@ -447,8 +447,9 @@ function lintMarkdown(files) {
  */
 function getFormatterResults() {
     const stripAnsi = require("strip-ansi");
+    const formattersMetadata = require("./lib/cli-engine/formatters/formatters-meta.json");
 
-    const formatterFiles = fs.readdirSync("./lib/cli-engine/formatters/"),
+    const formatterFiles = fs.readdirSync("./lib/cli-engine/formatters/").filter(fileName => !fileName.includes("formatters-meta.json")),
         rules = {
             "no-else-return": "warn",
             indent: ["warn", 4],
@@ -489,7 +490,8 @@ function getFormatterResults() {
             );
 
             data.formatterResults[name] = {
-                result: stripAnsi(formattedOutput)
+                result: stripAnsi(formattedOutput),
+                description: formattersMetadata.find(formatter => formatter.name === name).description
             };
         }
         return data;
diff --git a/lib/cli-engine/formatters/formatters-meta.json b/lib/cli-engine/formatters/formatters-meta.json
@@ -0,0 +1,46 @@
+[
+    {
+        "name": "checkstyle",
+        "description": "Outputs results to the [Checkstyle](https://checkstyle.sourceforge.io/) format."
+    },
+    {
+        "name": "compact",
+        "description": "Human-readable output format. Mimics the default output of JSHint."
+    },
+    {
+        "name": "html",
+        "description": "Outputs results to HTML. The `html` formatter is useful for visual presentation in the browser."
+    },
+    {
+        "name": "jslint-xml",
+        "description": "Outputs results to format compatible with the [JSLint Jenkins plugin](https://plugins.jenkins.io/jslint/)."
+    },
+    {
+        "name": "json-with-metadata",
+        "description": "Outputs JSON-serialized results. The `json-with-metadata` provides the same linting results as the [`json`](#json) formatter with additional metadata about the rules applied. The linting results are included in the `results` property and the rules metadata is included in the `metadata` property.\n\nAlternatively, you can use the [ESLint Node.js API](../../developer-guide/nodejs-api) to programmatically use ESLint."
+    },
+    {
+        "name": "json",
+        "description": "Outputs JSON-serialized results. The `json` formatter is useful when you want to programmatically work with the CLI's linting results.\n\nAlternatively, you can use the [ESLint Node.js API](../../developer-guide/nodejs-api) to programmatically use ESLint."
+    },
+    {
+        "name": "junit",
+        "description": "Outputs results to format compatible with the [JUnit Jenkins plugin](https://plugins.jenkins.io/junit/)."
+    },
+    {
+        "name": "stylish",
+        "description": "Human-readable output format. This is the default formatter."
+    },
+    {
+        "name": "tap",
+        "description": "Outputs results to the [Test Anything Protocol (TAP)](https://testanything.org/) specification format."
+    },
+    {
+        "name": "unix",
+        "description": "Outputs results to a format similar to many commands in UNIX-like systems. Parsable with tools such as [grep](https://www.gnu.org/software/grep/manual/grep.html), [sed](https://www.gnu.org/software/sed/manual/sed.html), and [awk](https://www.gnu.org/software/gawk/manual/gawk.html)."
+    },
+    {
+        "name": "visualstudio",
+        "description": "Outputs results to format compatible with the integrated terminal of the [Visual Studio](https://visualstudio.microsoft.com/) IDE. When using Visual Studio, you can click on the linting results in the integrated terminal to go to the issue in the source code."
+    }
+]
diff --git a/templates/formatter-examples.md.ejs b/templates/formatter-examples.md.ejs
@@ -10,7 +10,7 @@ edit_link: https://github.com/eslint/eslint/edit/main/templates/formatter-exampl
 
 ESLint comes with several built-in formatters to control the appearance of the linting results, and supports third-party formatters as well.
 
-You can specify a formatter using the `--format` or `-f` flag on the command line. For example, `--format json` uses the `json` formatter.
+You can specify a formatter using the `--format` or `-f` flag in the CLI. For example, `--format json` uses the `json` formatter.
 
 The built-in formatter options are:
 
@@ -20,9 +20,9 @@ The built-in formatter options are:
 
 ## Example Source
 
-Examples of each formatter were created from linting `fullOfProblems.js` using the `.eslintrc` configuration shown below.
+Examples of each formatter were created from linting `fullOfProblems.js` using the `.eslintrc.json` configuration shown below.
 
-### `fullOfProblems.js`
+`fullOfProblems.js`:
 
 ```js
 function addOne(i) {
@@ -34,7 +34,7 @@ function addOne(i) {
 };
 ```
 
-### `.eslintrc`
+`.eslintrc.json`:
 
 ```json
 {
@@ -49,17 +49,26 @@ function addOne(i) {
 }
 ```
 
-## Output Examples
+Tests the formatters with the CLI:
+
+```shell
+npx eslint --format <Add formatter here> fullOfProblems.js
+```
+
+## Built-In Formatter Options
 <% Object.keys(formatterResults).forEach(function(formatterName) { -%>
 
 ### <%= formatterName %>
-<% if (formatterName !== "html") { -%>
 
+<%= formatterResults[formatterName].description %>
+
+Example output:
+
+<% if (formatterName !== "html") { -%>
 ```text
 <%= formatterResults[formatterName].result %>
 ```
 <% } else {-%>
-
 <iframe src="html-formatter-example.html" width="100%" height="460px"></iframe>
 <% } -%>
 <% }) -%>
