From dfc7ec11b11b56daaa10e8e6d08c5cddfc8c2c59 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:54:56 -0500 Subject: [PATCH] docs: Formatters page updates (#16566) * 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 Co-authored-by: Milos Djermanovic --- Makefile.js | 6 ++- .../formatters/formatters-meta.json | 46 +++++++++++++++++++ templates/formatter-examples.md.ejs | 23 +++++++--- 3 files changed, 66 insertions(+), 9 deletions(-) create mode 100644 lib/cli-engine/formatters/formatters-meta.json diff --git a/Makefile.js b/Makefile.js index e85514db9d9..426dd9b717a 100644 --- 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 new file mode 100644 index 00000000000..a26ce8d2874 --- /dev/null +++ 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." + } +] \ No newline at end of file diff --git a/templates/formatter-examples.md.ejs b/templates/formatter-examples.md.ejs index 218cd8777c3..fb023798a67 100644 --- 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 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 {-%> - <% } -%> <% }) -%>