Automate docs with eslint-doc-generator

[bmish]

I built this CLI tool eslint-doc-generator for automating the generation of the README rules list table 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 custom rules through better documentation and streamline the process of adding new rules). It has 100% test coverage. It's already used in other popular plugins like eslint-plugin-react.

Notable changes:

• Moved rule categories from README to common meta.docs.category property and used eslint-doc-generator --split-by meta.docs.category to continue displaying multiple lists in the README
• Moved rule descriptions from README to standard meta.docs.description property which is consumable by tooling
• Enabled eslint-plugin/require-meta-docs-description for ensuring we have consistent descriptions defined in all rules

Rule doc headers now have consistent titles and helpful notices about autofixers and what configs the rules are enabled/disabled/warn in. The README rules list now has an attractive table containing much more information about the rules.

[ljharb]

i'd prefer to see this tagline preserved somewhere

[bmish]

A few of these rule docs had the rule description in their title. Note that these descriptions are all preserved in meta.docs.description which is used in the README rules table. If you wanted, we could include the rule descriptions in all the titles using the option --rule-doc-title-format option. But for the most part, these descriptions are already captured in the rule doc bodies.

[ljharb]

I think it's useful for the exact phrase to appear somewhere in the doc - it doesn't have to be in the title ofc, but somewhere. Can that be automated/enforced somehow?

[bmish]

Today, there are many plugins that include the rule description directly in the rule doc title, which is why we have --rule-doc-title-format desc-parens-prefix-name. That's probably the best/easiest way to achieve this within existing conventions.

That said, if that's still not satisfactory, then I'm thinking of some possible options that could achieve what you want.

Potential Option	Description	Upside	Downsides
--rule-doc-header-include-description	Whether to include the rule description below any notices at the bottom of the rule doc header (default false).	The rule description will be auto-generated in the rule doc header.	This isn't always the best place to put the rule description. Often, rule docs provide general context first, and then provide the description later (potentially in a "Rule details" section).
--rule-doc-section-include-description	Specifies the name of the section of the rule doc that should begin with the rule description. Pass option with no section name to include the description at the bottom of the rule doc header.	Ensures the rule description is mentioned in the appropriate section, often a "Rule details" section. This is a more flexible version of --rule-doc-header-include-description.	Most complex implementation.
--rule-doc-mention-description	Whether to require the rule description to be mentioned somewhere in the rule doc (default false).	Allows greatest flexibility in placement.	Not auto-generated. The descriptions could end up placed in inconsistent positions.

My recommendation in order of preference:

1. Leave as-is. Rule docs already capture the spirit of the description even if the wording doesn't exactly match.
2. Include rule descriptions in the rule doc titles.
3. Add --rule-doc-section-include-description option or --rule-doc-mention-description.

Let me know what you think. If we want to implement a new option, then it would probably be best to file an issue for this and avoid blocking the overall PR, since this only affected a few rule docs anyway.

[ljharb]

Hmm. I agree it needn't block the PR, regardless.

I think a simple tagline is important top-level context, so I'd prefer --rule-doc-section-include-description. Is that already implemented? If so, let's use it! If not, we can address it in the future.

[bmish]

Not implemented but I filed bmish/eslint-doc-generator#192 to track this.

[ljharb]

it seems like the superscripted emoji is still rendering on a new line, and isn't staying attached to the base emoji?

[bmish]

Ugh. I fixed some other issues with this but looks like I'm still struggling to get the emoji superscript to stay attached to its base character. Tracking this with: bmish/eslint-doc-generator#204

[bmish]

I tried everything to fix the emoji superscripts but they turned out to be too fragile. This led me to remove the superscripts entirely and switch to what I believe is a significantly better information architecture with a separate rules list column per severity and many other improvements:

• Redesign information architecture of rules table columns and rule doc notices for representing rule configs/severities bmish/eslint-doc-generator#205

[ljharb]

Looks great!

A possible enhancement would be if there's a way to provide tooltips (like an img alt) on all the emojis.

[bmish]

@ljharb based on my research, it's not possible to add alt text / tooltips on emojis in GitHub markdown. It could be nice but hopefully it won't be needed anyway.

[bmish]

Seems like there's an unrelated failure on CI with continuous-integration/appveyor/pr — AppVeyor build failed? I'd recommend merging and addressing that separately.

  1) dynamic imports no-unused-modules valid 
        import App from './App';
      :
     Error: Timeout of 5000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.

[ljharb]

@bmish i'll rerun it til it passes :-)