docs: CLI documentation standardization #16563

bpmutter · 2022-11-20T19:00:33Z

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)

Standardized the documentation for CLI commands.

Used the general format:

#### ``--my-option`

Short description of option 
* **Alias**: If applicable add short command alias (ex: `-mo`)
* **Argument Type**:  "No Argument." or argument data type and short description as necessary.
**Multiple Arguments**: "Yes"/"No". If argument type specified, add this saying whether it takes multiple arguments or not.
* **Default Value**: Add default value for command if applicable.

Additional guidance for usage.

##### `--my-option` example

Description of example, if necessary.

```shell
npx eslint ...example of command usage
```

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

Resolves #16475

Fixes eslint#16475

netlify · 2022-11-20T19:00:43Z

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	`b5f5c6e`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/63929a09a712fe000800ef3f
😎 Deploy Preview	https://deploy-preview-16563--docs-eslint.netlify.app/user-guide/command-line-interface
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

docs/src/user-guide/command-line-interface.md

mdjermanovic · 2022-11-21T12:01:24Z

docs/src/user-guide/command-line-interface.md


-Examples:
+These rules are merged with any rules specified with configuration files. If the rule is defined in a plugin, you have to prefix the rule ID with the plugin name and a `/`.


Perhaps we should keep the note about --no-eslintrc here?

i think i removed the line b/c i didn't understand what it was saying, and figured it wasn't too important b/c it's in parenthesis.

could you clarify what is meant by "You can use --no-eslintrc to change that behavior."? then i can add back in refactored, clearer form.

Agree with @bpmutter, I think it’s safe to omit this.

This was added in #2776 per #2773.

It explains how to run only the rules specified on the command line. Without --no-eslintrc, rules specified with config files will be run too. With --no-eslintrc, rules specified with --rule are not "merged with any rules specified with configuration files", meaning that the final list of rules to run is the list of rules specified with --rule.

I'm fine with removing the note, but it also makes sense to keep it here as it addresses one of the common use cases for --rule.

I think @bpmutter's point, and I agree, is that the current text isn't clear as to what --no-eslintrc does in this context. It's way to vague to be able to understand your point. We can either remove the parens and leave it, or we can update the text to more explicitly describe the situation you mention, but I don't think leaving as-is makes sense.

ok, thank you for the further clarification!

i added a sentence to explain and example in 0365e98

docs/src/user-guide/command-line-interface.md

mdjermanovic · 2022-12-02T00:16:57Z

docs/src/user-guide/command-line-interface.md

+
+* **Argument Type**: String. The supported syntax is the same as for [`.eslintignore` files](configuring/ignoring-code#the-eslintignore-file), which use the same patterns as the [`.gitignore` specification](https://git-scm.com/docs/gitignore). You should quote your patterns in order to avoid shell interpretation of glob patterns.
+* **Multiple Arguments**: Yes
+* **Default Value**: whatever the default value is OR N/A


This is TODO?

Suggested change

* **Default Value**: whatever the default value is OR N/A

* **Default Value**: None.

this line shouldn't have been included. sorry! removed

docs/src/user-guide/command-line-interface.md

nzakas · 2022-12-02T18:49:08Z

docs/src/user-guide/command-line-interface.md

+* **Argument Type**: String. One of the available environments.
+* **Multiple Arguments**: Yes
+
+Details about the global variables defined by each environment are available in the [Specifying Environments](configuring/language-options#specifying-environments) documentation. This option only enables environments. It does not disable environments set in other configuration files. To specify multiple environments, separate them using commas, or use the option multiple times.


Just double checking -- specifying vs. specify in the link?

yep, this is currently the name of the section

docs/src/user-guide/command-line-interface.md

nzakas · 2022-12-02T18:52:53Z

docs/src/user-guide/command-line-interface.md

+
+* **Argument Type**: String. The supported syntax is the same as for [`.eslintignore` files](configuring/ignoring-code#the-eslintignore-file), which use the same patterns as the [`.gitignore` specification](https://git-scm.com/docs/gitignore). You should quote your patterns in order to avoid shell interpretation of glob patterns.
+* **Multiple Arguments**: Yes
+* **Default Value**: whatever the default value is OR N/A


Suggested change

* **Default Value**: whatever the default value is OR N/A

* **Default Value**: None.

docs/src/user-guide/command-line-interface.md

nzakas · 2022-12-02T18:54:13Z

docs/src/user-guide/command-line-interface.md


 ```shell
 npm install eslint-formatter-pretty
-
+# THEN


I think this makes it read like you should do the first two lines OR the third, which is incorrect.

i'll add some clarification comments to the code example

added in 801544d

docs/src/user-guide/command-line-interface.md

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

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

@mdjermanovic and @nzakas ready for re-review

mdjermanovic · 2022-12-07T07:25:09Z

lib/options.js

@@ -191,7 +191,7 @@ module.exports = function(usingFlatConfig) {
            },
            rulesDirFlag,
            {
-                heading: "Fixing problems"
+                heading: "Fix problems"


Should we update these to Title Case as well?

I don't feel strongly either way.

i'll update. consistency!

nzakas

Updates LGTM. Just noticed one inconsistency.

docs/src/user-guide/command-line-interface.md

lib/options.js

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

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>

bpmutter added 5 commits November 20, 2022 13:25

docs: CLI intro + copy tweaks

701d9c7

docs: CLI docs standardization

54d3df6

Fixes eslint#16475

continue on standardization

814684e

finish first pass of formatting

30806ad

finish adding examples

90f7d86

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

Merge branch 'main' into cli_standardization

4bb597d

bpmutter marked this pull request as ready for review November 20, 2022 19:09

bpmutter added 2 commits November 20, 2022 14:24

fixes

d867068

copy edits

8af595c

mdjermanovic reviewed Nov 20, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

amareshsm reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

mdjermanovic mentioned this pull request Nov 21, 2022

chore: fix rule doc headers check #16564

Merged

1 task

mdjermanovic reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

mdjermanovic reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

mdjermanovic requested changes Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

mdjermanovic reviewed Nov 21, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

mdjermanovic reviewed Dec 2, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

nzakas requested changes Dec 2, 2022

View reviewed changes

bpmutter commented Dec 3, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

Apply suggestions from code review

0ab3202

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

bpmutter requested a review from a team as a code owner December 3, 2022 23:23

bpmutter and others added 3 commits December 3, 2022 18:42

clarify formatter example comments

801544d

Apply suggestions from code review

bbbc74e

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

standardize all headings to Title Case

55b7a94

bpmutter requested review from nzakas and mdjermanovic and removed request for nzakas December 6, 2022 00:35

mdjermanovic reviewed Dec 7, 2022

View reviewed changes

nzakas reviewed Dec 8, 2022

View reviewed changes

docs/src/user-guide/command-line-interface.md Outdated Show resolved Hide resolved

bpmutter commented Dec 9, 2022

View reviewed changes

lib/options.js Outdated Show resolved Hide resolved

bpmutter commented Dec 9, 2022

View reviewed changes

lib/options.js Outdated Show resolved Hide resolved

bpmutter commented Dec 9, 2022

View reviewed changes

lib/options.js Outdated Show resolved Hide resolved

bpmutter commented Dec 9, 2022

View reviewed changes

lib/options.js Outdated Show resolved Hide resolved

Apply suggestions from code review

b5f5c6e

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

bpmutter requested review from nzakas and mdjermanovic and removed request for nzakas December 9, 2022 02:14

mdjermanovic approved these changes Dec 9, 2022

View reviewed changes

nzakas approved these changes Dec 9, 2022

View reviewed changes

nzakas merged commit ad44344 into eslint:main Dec 9, 2022

github-actions bot mentioned this pull request May 2, 2023

Upgraded some dependencies - Attempt 2 AurorNZ/report-updated-dependencies#638

Merged

eslint-github-bot bot locked and limited conversation to collaborators Jun 8, 2023

eslint-github-bot bot added the archived due to age This issue has been archived; please open a new issue for any further discussion label Jun 8, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: CLI documentation standardization #16563

docs: CLI documentation standardization #16563

bpmutter commented Nov 20, 2022 •

edited

netlify bot commented Nov 20, 2022 •

edited

mdjermanovic Nov 21, 2022

bpmutter Nov 22, 2022

nzakas Nov 22, 2022

mdjermanovic Nov 23, 2022

nzakas Nov 23, 2022

bpmutter Nov 27, 2022

mdjermanovic Dec 2, 2022

nzakas Dec 2, 2022

bpmutter Dec 3, 2022

nzakas Dec 2, 2022

bpmutter Dec 3, 2022

nzakas Dec 2, 2022

nzakas Dec 2, 2022

bpmutter Dec 3, 2022

bpmutter Dec 3, 2022

bpmutter commented Dec 6, 2022

mdjermanovic Dec 7, 2022

nzakas Dec 8, 2022

bpmutter Dec 9, 2022

nzakas left a comment

mdjermanovic left a comment


		Examples:
		These rules are merged with any rules specified with configuration files. If the rule is defined in a plugin, you have to prefix the rule ID with the plugin name and a `/`.

	* Default Value: whatever the default value is OR N/A
	* Default Value: None.

docs: CLI documentation standardization #16563

docs: CLI documentation standardization #16563

Conversation

bpmutter commented Nov 20, 2022 • edited

Prerequisites checklist

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

What changes did you make? (Give an overview)

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

netlify bot commented Nov 20, 2022 • edited

✅ Deploy Preview for docs-eslint ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bpmutter commented Dec 6, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nzakas left a comment

Choose a reason for hiding this comment

mdjermanovic left a comment

Choose a reason for hiding this comment

bpmutter commented Nov 20, 2022 •

edited

netlify bot commented Nov 20, 2022 •

edited