Skip to content

Rework template for individual Rules pages #4365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
JoshuaKGoldberg opened this issue Dec 30, 2021 · 5 comments · Fixed by #5249
Closed

Rework template for individual Rules pages #4365

JoshuaKGoldberg opened this issue Dec 30, 2021 · 5 comments · Fixed by #5249
Assignees
Labels
accepting prs Go ahead, send a pull request that resolves this issue documentation Documentation ("docs") that needs adding/updating

Comments

@JoshuaKGoldberg
Copy link
Member

JoshuaKGoldberg commented Dec 30, 2021

Right now individual rules' pages have a somewhat unwieldy header based on their description. I'd like to swap that with a header equal to the rule name, and move that description into body text.

It'd be nice to also auto-generated an ESLint config snippet for enabling the rule...

Screenshot of the huge header on https://typescript-eslint.io/rules/adjacent-overload-signatures

@JoshuaKGoldberg JoshuaKGoldberg moved this from Todo to In Progress in Documentation Dec 30, 2021
@JoshuaKGoldberg JoshuaKGoldberg self-assigned this Dec 30, 2021
@JoshuaKGoldberg JoshuaKGoldberg added accepting prs Go ahead, send a pull request that resolves this issue documentation Documentation ("docs") that needs adding/updating labels Dec 30, 2021
@JoshuaKGoldberg JoshuaKGoldberg moved this from In Progress to In Review in Documentation Dec 30, 2021
@bradzacher
Copy link
Member

We used this style because it's the standard across the ESLint ecosystem.
I don't know if we should break from the standard unless we think it really imported the UX? Maybe we just need to work on better / clearer /ore succinct descriptions?

Examples:
https://eslint.org/docs/rules/array-callback-return
https://github.com/jest-community/eslint-plugin-jest/blob/HEAD/docs/rules/consistent-test-it.md
https://github.com/import-js/eslint-plugin-import/blob/HEAD/docs/rules/no-unresolved.md
https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/better-regex.md

@JoshuaKGoldberg
Copy link
Member Author

Oh that's very interesting. In general this is kind of a violation of what a heading is supposed to be, no? I don't know of any precedent for using the top level heading in a file to describe anything like this description. Is this exclusively in ESLint?

@bradzacher
Copy link
Member

I think the idea is that the title is kind of just the tagline for the rule to help people figure out what it does at a glance to save them reading the entire page?

I'm not sure exactly! This convention came from people copying the ESLint core docs.

@JoshuaKGoldberg
Copy link
Member Author

Moved to ESLint core: eslint/eslint#15471

@JoshuaKGoldberg JoshuaKGoldberg moved this from In Review to In Progress in Documentation Dec 31, 2021
@JoshuaKGoldberg
Copy link
Member Author

Per eslint/eslint#15471 I think we can consider this accepting PRs! 🙌

@JoshuaKGoldberg JoshuaKGoldberg moved this from In Progress to In Review in Documentation Jan 24, 2022
Repository owner moved this from In Review to Done in Documentation Jul 22, 2022
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 22, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
accepting prs Go ahead, send a pull request that resolves this issue documentation Documentation ("docs") that needs adding/updating
Projects
No open projects
Status: Done
2 participants