Skip to content
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

Automate docs with eslint-doc-generator #3469

Merged
merged 1 commit into from Oct 26, 2022

Conversation

bmish
Copy link
Contributor

@bmish bmish commented Oct 20, 2022

I built this CLI tool eslint-doc-generator for automating the generation of the README rules list and rule doc title/notices for ESLint plugins. It follows common documentation conventions from this and other top ESLint plugins and will help us standardize documentation across ESLint plugins (and generally improve the usability of our custom rules through better documentation and streamline the process of adding new rules).

This is a follow-up to the work I did to add the original notices in #3359 #3361 #3364 #3362. eslint-doc-generator is significantly more robust compared to the previous documentation generator script/tests which I have now removed. It has additional functionality (for example, the rules list legend is auto-generated, and the rules list will show additional columns of information when applicable) and 100% test coverage.

There are some discrepancies between the old docs and the new docs. Most of these are intentional and likely improvements. If you don't like any of the changes, let me know and I may be able to tweak eslint-doc-generator or add a config option to support the desired behavior.

@codecov
Copy link

codecov bot commented Oct 20, 2022

Codecov Report

Merging #3469 (bb881e4) into master (bb881e4) will not change coverage.
The diff coverage is n/a.

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

@@           Coverage Diff           @@
##           master    #3469   +/-   ##
=======================================
  Coverage   97.57%   97.57%           
=======================================
  Files         129      129           
  Lines        9192     9192           
  Branches     3331     3331           
=======================================
  Hits         8969     8969           
  Misses        223      223           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

.github/workflows/readme.yml Show resolved Hide resolved
@@ -276,12 +276,6 @@ module.exports = {
schema: [{
type: 'object',
properties: {
customValidators: {
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This option appears to be unused in this rule. eslint-doc-generator caught this because it checks that all rule options are mentioned in the rule doc.

Copy link
Member

Choose a reason for hiding this comment

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

It's used by the propTypes util, so even if it's missing documentation, it's still used.

The docs are never the source of truth, only the code is, so that "catch" seems a bit backwards.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I also checked the tests for this rule and didn't see the option tested. That seems like an issue. I'll add the option back.

Copy link
Member

Choose a reason for hiding this comment

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

Indeed, missing tests is far more worrisome than missing docs, but either way removing the option could break people, so we'll need to add the missing tests/docs :-) thanks for noticing!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added the option back and mentioned it in the docs. Someone should follow-up separately to add the missing test.

docs/rules/jsx-uses-react.md Show resolved Hide resolved
docs/rules/jsx-no-duplicate-props.md Outdated Show resolved Hide resolved
docs/rules/jsx-sort-default-props.md Outdated Show resolved Hide resolved

<!-- end rule header -->

Please use the `"beforeSelfClosing"` option of the [jsx-tag-spacing](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-tag-spacing.md) rule instead.
Copy link
Member

Choose a reason for hiding this comment

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

it'd be better to keep this attached to the deprecation message if possible

Copy link
Contributor Author

@bmish bmish Oct 20, 2022

Choose a reason for hiding this comment

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

While the standard meta.replacedBy rule field allows the replacement rule to be indicated, there's no way for us to indicate a "replacement option" using the rule metadata. So currently there's no practical means for including this in the autogenerated content. Personally, it seems fine to me if some additional information about the deprecation comes later in the rule doc. Some people might want to expand on the deprecation with an entire paragraph anyway.

Copy link
Member

Choose a reason for hiding this comment

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

hmm - standard wrt eslint itself?

Perhaps replacedBy could be extended to also support an object, with "rule" and "notes" or something?

Copy link
Contributor Author

@bmish bmish Oct 21, 2022

Choose a reason for hiding this comment

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

meta.replacedBy is defined as string array here:

So while I do think a "deprecation message" field would generally be useful and could be used for the purpose you suggest, it would take a concerted effort to propose and update various definitions and tooling to handle objects like that. For now, I recommend we just expand on deprecations later in the rule doc.

Copy link
Member

Choose a reason for hiding this comment

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

Sounds good, but it'd be great to pursue making that change :-)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I could file an issue in ESLint suggesting it. I hope it wouldn't block this PR.

Here's a potential API allowing deprecation messages about each specific replacement rule, or a general deprecation message (not specific to any replacement). Let me know if you like it.

replacedBy: ["replacement-rule-name"]
replacedBy: [{ name: "replacement-rule-name" }]
replacedBy: [{ name: "replacement-rule-name", message: "some deprecation message specific to this replacement" }]
replacedBy: [{ message: "general deprecation message" }]

Copy link
Member

Choose a reason for hiding this comment

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

It wouldn’t block it. Your suggested schema seems awesome and backwards compatible.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

docs/rules/no-find-dom-node.md Outdated Show resolved Hide resolved
docs/rules/require-render-return.md Outdated Show resolved Hide resolved
lib/rules/no-unstable-nested-components.js Outdated Show resolved Hide resolved
package.json Outdated Show resolved Hide resolved
package.json Outdated Show resolved Hide resolved
@ljharb
Copy link
Member

ljharb commented Oct 21, 2022

@bmish btw i failed to mention this in the main comment of my review, but thank you, this is awesome!

@ljharb ljharb force-pushed the eslint-doc-generator branch 2 times, most recently from de26e0f to 484f40d Compare October 26, 2022 19:58
💡 Manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).\
❌ Deprecated.

| Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Description | 💼 | 🔧 | 💡 | ❌ |
Copy link
Member

Choose a reason for hiding this comment

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

what's the deal with all these nonbreaking spaces? i don't think markdown tables require them

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This minimizes line-breaking/word-wrapping in the rule name column so that we can see complete rule names more easily.

Context: bmish/eslint-doc-generator#110

Copy link
Member

Choose a reason for hiding this comment

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

oof, ok - can they be actual nonbreaking spaces instead of html ones, or will markdown parsers break on that?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Interesting idea, I'll give that a try.

Copy link
Member

Choose a reason for hiding this comment

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

I'll merge this as-is; if that can be made cleaner then I'd appreciate a followup :-)

Copy link
Contributor Author

@bmish bmish Oct 26, 2022

Choose a reason for hiding this comment

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

It appears to work: bmish/eslint-doc-generator#172

The good news is that you'll receive any improvements like this when future versions of the tool are released.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging this pull request may close these issues.

None yet

2 participants