chore(website): generate rule docs options automatically

[JoshuaKGoldberg]

PR Checklist

• Addresses an existing open issue: fixes Docs: Automate the Options heading in rule docs pages #5058
• That issue was marked as accepting prs
• Steps in CONTRIBUTING.md were taken

Overview

Uses even more fancy Markdown AST manipulations in the generated-rule-docs.ts Docusaurus plugin to automate the creation of much of the rules docs pages.

• ## How to Use, and `## Options are added if they don't yet exist
• Contents are added to the beginning of ## Options:
  • Base rule extensions have a link to the base rule's options
  • An .eslintrc.cjs snippet adds in the suggested config usage
  • If the rule isn't configurable, the This rule is not configurable. text is added
  • If the rule is configurable, json-schema-to-typescript and prettier are used to print the types and defaultConfig
• description fields are used in rule schema metadata instead of .md explanations

Assorted other standardizations:

• Using Docusaurus admonitions for deprecation notices and the like
• Explaining default options is moved under ## Options (e.g. ban-ts-comment.md)
• Properly using tabs in at least ban-types.md
• Listing out string literal options (e.g. comma-dangle.md)
• Using /* eslint ... */ comments in options examples

Some old todos from when this PR was a draft should be done:

• get Options heading in right sidebar ✅
• see if json-schema-to-typescript can make shared types for repeated shapes this week I learned, definitions properties are the intended way to explicitly do that in json-schema ✨ ✅
• finish trimming down more rule docs .md files ✅

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit cfd750d. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

---

✅ Successfully ran 47 targets

• Node 18 - nx test @typescript-eslint/eslint-plugin
• Node 12 - nx test @typescript-eslint/eslint-plugin --coverage=false
• nx run-many --target=build --all --parallel --exclude website
• Node 12 - nx test @typescript-eslint/typescript-estree --coverage=false
• Node 18 - nx test @typescript-eslint/type-utils
• Node 18 - nx test @typescript-eslint/visitor-keys
• Node 18 - nx test @typescript-eslint/typescript-estree
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx test @typescript-eslint/utils
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx test @typescript-eslint/scope-manager
• nx run-many --target=typecheck --all --parallel
• Node 12 - nx test @typescript-eslint/scope-manager --coverage=false
• nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx test @typescript-eslint/ast-spec
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx test @typescript-eslint/type-utils --coverage=false
• Node 18 - nx test @typescript-eslint/eslint-plugin-internal
• Node 18 - nx test @typescript-eslint/parser
• Node 12 - nx test @typescript-eslint/ast-spec --coverage=false
• nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx test @typescript-eslint/parser --coverage=false
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx test @typescript-eslint/eslint-plugin-tslint
• Node 12 - nx test @typescript-eslint/visitor-keys --coverage=false
• Node 12 - nx test @typescript-eslint/eslint-plugin-internal --coverage=false
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx test @typescript-eslint/utils --coverage=false
• Node 12 - nx test @typescript-eslint/eslint-plugin-tslint --coverage=false
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 18 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12 - nx run-many --target=build --all --parallel --exclude website --exclude website
• nx run-many --target=build --all --parallel --exclude website --exclude website

---

Sent with 💌 from NxCloud.

[typescript-eslint]

Thanks for the PR, @JoshuaKGoldberg!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

---

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. As a thank you, your profile/company logo will be added to our main README which receives thousands of unique visitors per day.

[netlify]

✅ Deploy Preview for typescript-eslint ready!

Name	Link
🔨 Latest commit	cfd750d
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/62fd2cc1d601b70008c0dc47
😎 Deploy Preview	https://deploy-preview-5386--typescript-eslint.netlify.app
📱 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.

[Josh-Cena]

• get Options heading in right sidebar

You need to move this remark plugin from remarkPlugins to beforeDefaultRemarkPlugins. See https://docusaurus.io/docs/markdown-features/plugins#creating-new-rehyperemark-plugins

[armano2]

are we planning to add description fields to schema of rules, for describing specific options?

https://deploy-preview-5386--typescript-eslint.netlify.app/rules/explicit-function-return-type#options

https://json-schema.org/draft/2020-12/json-schema-core.html#name-schema-vocabularies

[bradzacher]

@armano2 i was thinking that would be an awesome thing to do! Already suggested!

https://twitter.com/bradzacher/status/1552009532124958720

It would be a decent chunk of work to add the descriptions for everything up-front.

Side note: would be easy to write a lint rule to enforce all schemas define descriptions.

[bradzacher]

https://deploy-preview-5386--typescript-eslint.netlify.app/rules/explicit-function-return-type

This one seems to be broken:

---

This is looking good to me - I spot checked a number and they looked good!

[bradzacher]

[bradzacher]

@JoshuaKGoldberg resolve the conflicts and we can merge this!