handle "Resources" section #808
Description
- On every ESLint rule, they have a "Resources" section: https://eslint.org/docs/latest/rules/array-callback-return#resources
- Similarly, on every TSESLint rule, they have a "Resources" section: https://typescript-eslint.io/rules/adjacent-overload-signatures#resources
It appears that ESLint and TSESLint use an identical format, with the small exception of ESLint using "Tests" and TSESLint using "Test".
In any case, I think that this establishes that having a "Resources" section in your rule documentation is considered best practice. Thus, I propose that this doc generator should automatically create a section in the same format.
Other Solutions Considered
Right now, I use eslint-doc-generator to append a resources section at the end using a postprocess function like this:
/**
* Add a "Resources" section as the final section.
*
* @param content {string}
* @param pathToFile {string}
* @returns {string}
*/
function getContentWithResourcesSection(content, pathToFile) {
const ruleName = pathToFile.split(path.sep).pop().replace(".md", "");
const resourcesSection = `## Resources
- [Rule source](https://github.com/complete-ts/complete/blob/main/packages/eslint-plugin-complete/src/rules/${ruleName}.ts)
- [Test source](https://github.com/complete-ts/complete/blob/main/packages/eslint-plugin-complete/tests/rules/${ruleName}.test.ts)
`;
const resourcesIndex = content.indexOf("## Resources");
if (resourcesIndex !== -1) {
content = content.slice(0, resourcesIndex);
}
return `${content.trim()}\n\n${resourcesSection}`;
}However, this is quite verbose, and I think this should just be handled automatically by eslint-doc-generator itself.