Automate docs with eslint-doc-generator #901
Conversation
Codecov Report
@@ Coverage Diff @@
## main #901 +/- ##
=======================================
Coverage 99.29% 99.29%
=======================================
Files 103 103
Lines 1571 1571
Branches 514 514
=======================================
Hits 1560 1560
Misses 11 11
Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. |
bmish
force-pushed
the
eslint-doc-generator
branch
2 times, most recently
from
c804098 to
bfdc5cf
Compare
bmish
force-pushed
the
eslint-doc-generator
branch
from
9dd3ce1 to
03b41b5
Compare
| | :----------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :---- | :-- | | ||
| | [accessible-emoji](docs/rules/accessible-emoji.md) | | | ❌ | | ||
| | [alt-text](docs/rules/alt-text.md) | Enforce all elements that require alternative text have meaningful information to relay back to end user. | ☑️ 🔒 | | | ||
| | [anchor-ambiguous-text](docs/rules/anchor-ambiguous-text.md) | Enforce `<a>` text to not exactly match "click here", "here", "link", or "a link". | | | |
There was a problem hiding this comment.
is there an easy way to make these links be footnoted, so this could be:
| | [anchor-ambiguous-text](docs/rules/anchor-ambiguous-text.md) | Enforce `<a>` text to not exactly match "click here", "here", "link", or "a link". | | | | |
| | [anchor-ambiguous-text] | Enforce `<a>` text to not exactly match "click here", "here", "link", or "a link". | | | |
and the raw table would be smaller?
There was a problem hiding this comment.
That would make the table markdown more aesthetic, but I'm not sure that matters much since it's generated and managed by the tool.
Now if we expected or wanted to support the rule names being linked to from elsewhere in the readme, I could see an argument for switching to the reusable footnote link style, or perhaps having an option to switch to footnote links, but it would be good to spell out a use case for that first.
There was a problem hiding this comment.
A downside of switching to the footnote links is doubling the managed markdown height (from the table + the list of rule links).
There was a problem hiding this comment.
I feel like that's less of an issue, personally, since it's easier for humans to read the narrower table.
Certainly not a blocker, but I do think it would be an advantage to use footnotes.
There was a problem hiding this comment.
I'm not sure I'm going to pursue this idea at the moment, but I'll at least track it here: bmish/eslint-doc-generator#189
ljharb
force-pushed
the
eslint-doc-generator
branch
from
03b41b5 to
6d7a857
Compare
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 builds on some of the documentation work done by @uncommon-type in #837. eslint-doc-generator is more robust compared to the previous documentation generator script 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. An equivalent PR to eslint-plugin-react was also merged recently: jsx-eslint/eslint-plugin-react#3469.
Closes #903.