Skip to content

docs: standardized rule docs heading and option-less Options #4367

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 8 commits into from
Jan 30, 2022
Merged

docs: standardized rule docs heading and option-less Options #4367

merged 8 commits into from
Jan 30, 2022

Conversation

JoshuaKGoldberg
Copy link
Member

PR Checklist

Overview

Applies two changes to all rules .md docs files:

  • Changes the top-level heading to be just the rule name, with the description as the following paragraph
  • Enforces an ## Options section with a jsonc snippet for just the recommended, non-extension rules without options
Fun little script I used to rewrite all rule docs file headings: 
const fs = require('fs');

const dir = fs
  .readdirSync(__dirname)
  .filter(fileName => !fileName.includes('README'));

for (const fileName of dir) {
  const ruleName = fileName.split('.')[0];
  const contents = fs.readFileSync(fileName).toString();
  const firstHeader = contents.match(/^\# (.*)/g)?.[0];
  if (!firstHeader) {
    continue;
  }

  const description = `${firstHeader
    .slice(2)
    .replace(` (\`${ruleName}\`)`, '')}.`;

  const replaced = [
    `# \`${ruleName}\``,
    '',
    description,
    '',
    contents.slice(firstHeader.length + 2),
  ].join('\n');

  fs.writeFileSync(fileName, replaced);
}

@nx-cloud
Copy link

nx-cloud bot commented Dec 30, 2021 •
edited
Loading

☁️ Nx Cloud Report

CI ran the following commands for commit fc3404b. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

✅ Successfully ran 48 targets

Sent with 💌 from NxCloud.

@typescript-eslint
Copy link
Contributor

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
Copy link

netlify bot commented Dec 30, 2021 •
edited
Loading

✔️ Deploy Preview for typescript-eslint ready!

🔨 Explore the source changes: fc3404b

🔍 Inspect the deploy log: https://app.netlify.com/sites/typescript-eslint/deploys/61f570220b32b00008f89750

😎 Browse the preview: https://deploy-preview-4367--typescript-eslint.netlify.app

@JoshuaKGoldberg JoshuaKGoldberg marked this pull request as ready for review December 30, 2021 17:58
@JoshuaKGoldberg
Copy link
Member Author

Drafting pending resolution in #4365.

@JoshuaKGoldberg JoshuaKGoldberg marked this pull request as draft December 31, 2021 17:32
@bradzacher bradzacher added the documentation Documentation ("docs") that needs adding/updating label Jan 1, 2022
bradzacher
bradzacher reviewed Jan 1, 2022
View reviewed changes
Copy link
Member

@bradzacher bradzacher left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it'd be good to create a blank .md file that people can use as a template when creating a new rule doc. That would make it super easy for people to adhere to the style/layout without going through a test to check.

otherwise people end up copy-pasting an old rule and then sometimes we have bad text in docs.

@JoshuaKGoldberg JoshuaKGoldberg marked this pull request as ready for review January 23, 2022 22:25
@codecov
Copy link

codecov bot commented Jan 23, 2022 •
edited
Loading

Codecov Report

Merging #4367 (fed1694) into main (d4768c0) will increase coverage by 7.40%.
The diff coverage is n/a.

❗ Current head fed1694 differs from pull request most recent head fc3404b. Consider uploading reports for the commit fc3404b to get more accurate results

@@            Coverage Diff             @@
##             main    #4367      +/-   ##
==========================================
+ Coverage   86.97%   94.38%   +7.40%     
==========================================
  Files           5      164     +159     
  Lines         215     9235    +9020     
  Branches       60     2889    +2829     
==========================================
+ Hits          187     8716    +8529     
- Misses         22      300     +278     
- Partials        6      219     +213
Flag Coverage Δ
unittest 94.38% <ø> (+7.40%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files Coverage Δ
...internal/src/rules/no-typescript-default-import.ts
...plugin-internal/src/rules/prefer-ast-types-enum.ts
...gin-internal/src/rules/no-poorly-typed-ts-props.ts
...-internal/src/rules/no-typescript-estree-import.ts
...lugin-internal/src/rules/plugin-test-formatting.ts
packages/eslint-plugin/src/rules/no-redeclare.ts 91.89% <0.00%> (ø)
packages/eslint-plugin/src/rules/return-await.ts 99.00% <0.00%> (ø)
...s/eslint-plugin/src/rules/no-implicit-any-catch.ts 84.61% <0.00%> (ø)
...lugin/src/rules/padding-line-between-statements.ts 93.83% <0.00%> (ø)
...slint-plugin/src/rules/prefer-namespace-keyword.ts 100.00% <0.00%> (ø)
... and 159 more

bradzacher
bradzacher previously approved these changes Jan 24, 2022
View reviewed changes
@JoshuaKGoldberg JoshuaKGoldberg enabled auto-merge (squash) January 29, 2022 15:53
@bradzacher
Copy link
Member

image

@bradzacher bradzacher disabled auto-merge January 30, 2022 21:21
@bradzacher bradzacher merged commit 04baac8 into typescript-eslint:main Jan 30, 2022
@JoshuaKGoldberg JoshuaKGoldberg deleted the standard-rule-docs-heading branch January 30, 2022 21:40
lonyele pushed a commit to lonyele/typescript-eslint that referenced this pull request Feb 12, 2022
@lonyele
docs: standardized rule docs heading and option-less Options (typescr…
1c8895f 
…ipt-eslint#4367)
@JoshuaKGoldberg JoshuaKGoldberg mentioned this pull request Feb 13, 2022
Merged
3 tasks
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 2, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@bradzacher bradzacher bradzacher approved these changes

Assignees
No one assigned
Labels
documentation Documentation ("docs") that needs adding/updating
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@JoshuaKGoldberg @bradzacher