docs: Formatters page updates #16566

bpmutter · 2022-11-22T02:05:15Z

Prerequisites checklist

I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Miscellaneous changes on Formatters page:

In the example source section, make fullOfProblems.js and .eslintrc: not headers.
For the Example Outputs section, provide an example of the CLI input, and also give a few sentence description of what each of the output is, and why you might want to use it.
Other small cosmetic changes and refactors

Is there anything you'd like reviewers to focus on?

Fixes #16476

netlify · 2022-11-22T02:05:20Z

✅ Deploy Preview for docs-eslint canceled.

Name	Link
🔨 Latest commit	`7658246`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/638bd5ae7002370007010537

docs/src/user-guide/formatters/index.md

nzakas · 2022-11-23T19:52:04Z

docs/src/user-guide/formatters/index.md

@@ -42,7 +42,7 @@ function addOne(i) {
 };
 ```

-### `.eslintrc`
+`.eslintrc`:


While we're at it, let's use a file extension:

Suggested change

`.eslintrc`:

`.eslintrc.json`:

docs/src/user-guide/formatters/index.md

nzakas

Note: This page is autogenerated. Any changes made here will go live but will be overwrriten the next time the site is generated. The evergreen changes should be made in this file:

https://github.com/eslint/eslint/blob/main/templates/formatter-examples.md.ejs

bpmutter · 2022-11-27T18:47:04Z

@nzakas and @mdjermanovic thank you for the context! i'll try to fill out all the descriptions with this information. will let you know in comments if need any further clarification here.

and regarding:

Note: This page is autogenerated. Any changes made here will go live but will be overwrriten the next time the site is generated. The evergreen changes should be made in this file:

https://github.com/eslint/eslint/blob/main/templates/formatter-examples.md.ejs

at first glance, i understand what's going on with the template conceptually, but am not sure how i'd add the descriptions to it. will dig in a bit, and let you know if any questions.

if i cannot figure out how to add the descriptions to the template, i'll add them to the markdown file, so we can at least get the copy down before later adding it to the template file.

add more information about the built-in formatters Fixes eslint#16476

bpmutter · 2022-11-27T21:49:26Z

i've updated the code to include descriptions in the templates by adding a _manifest.js file to the source code, which contains the descriptions.

i've also:

updated the template to include descriptions and changes that were previously made to docs/src/user-guide/formatters/index.md.
reverted the changes to docs/src/user-guide/formatters/index.md since the page is generated.

generate the output as expected, you can run npm run gensite.

i'm not convinced that using the _manifest.js file as is done here is the best approach for including descriptions from the source code, even if it is effective. i look forward to the maintainer team's feedback on if/how to refactor this.

nzakas · 2022-11-30T21:19:13Z

lib/cli-engine/formatters/_manifest.js

@@ -0,0 +1,64 @@
+/**


Because this is just data, can we just create a JSON file here? I'd call it formatter-data.json and you'd still be able to require() it, but would otherwise be ignored.

sgtm, i like this approach

bpmutter · 2022-11-30T23:49:12Z

@nzakas implemented w the file named formatter-meta.json to align w the file naming convention of rules-meta.json

nzakas

LGTM. Would like @mdjermanovic to review before merging.

lib/cli-engine/formatters/formatters-meta.json

templates/formatter-examples.md.ejs

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

bpmutter · 2022-12-06T00:55:52Z

@mdjermanovic ready for re-review!

mdjermanovic

LGTM, thanks!

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [eslint](https://eslint.org) ([source](https://github.com/eslint/eslint)) | devDependencies | minor | [`8.29.0` -> `8.30.0`](https://renovatebot.com/diffs/npm/eslint/8.29.0/8.30.0) | --- ### Release Notes <details> <summary>eslint/eslint</summary> ### [`v8.30.0`](https://github.com/eslint/eslint/releases/tag/v8.30.0) [Compare Source](eslint/eslint@v8.29.0...v8.30.0) #### Features - [`075ef2c`](eslint/eslint@075ef2c) feat: add suggestion for no-return-await ([#16637](eslint/eslint#16637)) (Daniel Bartholomae) - [`7190d98`](eslint/eslint@7190d98) feat: update globals ([#16654](eslint/eslint#16654)) (Sébastien Règne) #### Bug Fixes - [`1a327aa`](eslint/eslint@1a327aa) fix: Ensure flat config unignores work consistently like eslintrc ([#16579](eslint/eslint#16579)) (Nicholas C. Zakas) - [`9b8bb72`](eslint/eslint@9b8bb72) fix: autofix recursive functions in no-var ([#16611](eslint/eslint#16611)) (Milos Djermanovic) #### Documentation - [`6a8cd94`](eslint/eslint@6a8cd94) docs: Clarify Discord info in issue template config ([#16663](eslint/eslint#16663)) (Nicholas C. Zakas) - [`ad44344`](eslint/eslint@ad44344) docs: CLI documentation standardization ([#16563](eslint/eslint#16563)) (Ben Perlmutter) - [`293573e`](eslint/eslint@293573e) docs: fix broken line numbers ([#16606](eslint/eslint#16606)) (Sam Chen) - [`fa2c64b`](eslint/eslint@fa2c64b) docs: use relative links for internal links ([#16631](eslint/eslint#16631)) (Percy Ma) - [`75276c9`](eslint/eslint@75276c9) docs: reorder options in no-unused-vars ([#16625](eslint/eslint#16625)) (Milos Djermanovic) - [`7276fe5`](eslint/eslint@7276fe5) docs: Fix anchor in URL ([#16628](eslint/eslint#16628)) (Karl Horky) - [`6bef135`](eslint/eslint@6bef135) docs: don't apply layouts to html formatter example ([#16591](eslint/eslint#16591)) (Tanuj Kanti) - [`dfc7ec1`](eslint/eslint@dfc7ec1) docs: Formatters page updates ([#16566](eslint/eslint#16566)) (Ben Perlmutter) - [`8ba124c`](eslint/eslint@8ba124c) docs: update the `prefer-const` example ([#16607](eslint/eslint#16607)) (Pavel) - [`e6cb05a`](eslint/eslint@e6cb05a) docs: fix css leaking ([#16603](eslint/eslint#16603)) (Sam Chen) #### Chores - [`f2c4737`](eslint/eslint@f2c4737) chore: upgrade [@eslint/eslintrc](https://github.com/eslint/eslintrc)[@1](https://github.com/1).4.0 ([#16675](eslint/eslint#16675)) (Milos Djermanovic) - [`ba74253`](eslint/eslint@ba74253) chore: standardize npm script names per [#14827](eslint/eslint#14827) ([#16315](eslint/eslint#16315)) (Patrick McElhaney) - [`0d9af4c`](eslint/eslint@0d9af4c) ci: fix npm v9 problem with `file:` ([#16664](eslint/eslint#16664)) (Milos Djermanovic) - [`90c9219`](eslint/eslint@90c9219) refactor: migrate off deprecated function-style rules in all tests ([#16618](eslint/eslint#16618)) (Bryan Mishkin) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: cabr2-bot <cabr2.help@gmail.com> Reviewed-on: https://codeberg.org/Calciumdibromid/CaBr2/pulls/1689 Reviewed-by: Epsilon_02 <epsilon_02@noreply.codeberg.org> Co-authored-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org> Co-committed-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>

eslint-github-bot bot added triage An ESLint team member will look at this issue soon documentation Relates to ESLint's documentation labels Nov 22, 2022