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.

[lo1tuma]

Thanks for pushing this. A while ago there was a similar request here from @edg2s. Can you elaborate what eslint-doc-generator can do better than eslint-docgen? Also please note, that this project doesn’t publish the docs anywhere and doesn’t have any kind of build and or release process. So how should we make sure the docs are always re-generated when the rules are changed?

[bmish]

@lo1tuma thanks for calling that out. I haven't fully reviewed the differences between eslint-docgen and my tool eslint-doc-generator yet. A few of the bigger differences I see so far:

• eslint-docgen adds examples generated from test cases to rule docs, whereas eslint-doc-generator does not manage examples
• eslint-doc-generator automatically creates a README rules table + legend with relevant columns of information, whereas eslint-docgen requires the user to implement a custom script for this
• eslint-doc-generator is written in TypeScript whereas eslint-docgen is written in JavaScript
• I have tested eslint-doc-generator in 10+ top ESLint plugins so it's robust and lightweight to introduce.

Obviously, I'm biased since I'm actively developing eslint-doc-generator right now. Regardless of which you choose, it looks like there could be an opportunity for the two tools to learn from each other.

[bmish]

Also please note, that this project doesn’t publish the docs anywhere and doesn’t have any kind of build and or release process. So how should we make sure the docs are always re-generated when the rules are changed?

@lo1tuma I've added a lint:eslint-docs script in package.json that will ensure the docs are up-to-date on CI. Contributors will want to run npm run update:eslint-docs and check-in the results when creating a PR.

[bmish]

Just a heads up that this PR is still ready. I'm just updating it whenever I publish a new version of the tool.

[lo1tuma]

@bmish sorry for the late response and thanks for the contribution, I’m definitely interested to generate at least some part of the documentation automatically. Unfortunately I didn’t find enough time yet to take a closer look. I hope I will get to it in the next days.

[bmish]

eslint-doc-generator has hit version 1.0.0 🎉. Now is a good time to consider it.