Include any mandatory sections when generating new rule docs with `--…

…init-rule-docs` and `--rule-doc-section-include` (#486)
bmish · Oct 15, 2023 · eed7d44 · eed7d44
1 parent 2593c13
commit eed7d44
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 6 deletions.
diff --git a/lib/generator.ts b/lib/generator.ts
@@ -161,13 +161,24 @@ export async function generate(path: string, options?: GenerateOptions) {
         );
       }
 
-      mkdirSync(dirname(pathToDoc), { recursive: true });
-      writeFileSync(
-        pathToDoc,
+      // Determine content for fresh rule doc, including any mandatory sections.
+      // The rule doc header will be added later.
+      let newRuleDocContents = [
+        ruleDocSectionInclude.length > 0
+          ? ruleDocSectionInclude.map((title) => `## ${title}`).join('\n\n')
+          : undefined,
         ruleHasOptions
-          ? `\n## Options\n\n${BEGIN_RULE_OPTIONS_LIST_MARKER}\n${END_RULE_OPTIONS_LIST_MARKER}\n`
-          : ''
-      );
+          ? `## Options\n\n${BEGIN_RULE_OPTIONS_LIST_MARKER}\n${END_RULE_OPTIONS_LIST_MARKER}`
+          : undefined,
+      ]
+        .filter((section) => section !== undefined)
+        .join('\n\n');
+      if (newRuleDocContents !== '') {
+        newRuleDocContents = `\n${newRuleDocContents}\n`;
+      }
+
+      mkdirSync(dirname(pathToDoc), { recursive: true });
+      writeFileSync(pathToDoc, newRuleDocContents);
       initializedRuleDoc = true;
     }
 

diff --git a/test/lib/generate/__snapshots__/file-paths-test.ts.snap b/test/lib/generate/__snapshots__/file-paths-test.ts.snap
@@ -61,6 +61,34 @@ exports[`generate (file paths) missing rule doc when initRuleDocs is true create
 "
 `;
 
+exports[`generate (file paths) missing rule doc, initRuleDocs is true, and with ruleDocSectionInclude creates the rule doc including the mandatory section 1`] = `
+"# test/no-foo
+
+<!-- end auto-generated rule header -->
+
+## Examples
+"
+`;
+
+exports[`generate (file paths) missing rule doc, initRuleDocs is true, and with ruleDocSectionInclude creates the rule doc including the mandatory section 2`] = `
+"# test/no-bar
+
+<!-- end auto-generated rule header -->
+
+## Examples
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name      |
+| :-------- |
+| \`option1\` |
+
+<!-- end auto-generated rule options list -->
+"
+`;
+
 exports[`generate (file paths) multiple rules lists generates the documentation 1`] = `
 "<!-- begin auto-generated rules list -->
 

diff --git a/test/lib/generate/file-paths-test.ts b/test/lib/generate/file-paths-test.ts
@@ -64,6 +64,52 @@ describe('generate (file paths)', function () {
     });
   });
 
+  describe('missing rule doc, initRuleDocs is true, and with ruleDocSectionInclude', function () {
+    beforeEach(function () {
+      mockFs({
+        'package.json': JSON.stringify({
+          name: 'eslint-plugin-test',
+          exports: 'index.js',
+          type: 'module',
+        }),
+
+        'index.js': `
+          export default {
+            rules: {
+              'no-foo': {
+                meta: { },
+                create(context) {}
+              },
+              'no-bar': {
+                meta: { schema: [{ type: 'object', properties: { option1: {} } }] },
+                create(context) {}
+              },
+            },
+          };`,
+
+        'README.md':
+          '<!-- begin auto-generated rules list --><!-- end auto-generated rules list -->',
+
+        // Needed for some of the test infrastructure to work.
+        node_modules: mockFs.load(PATH_NODE_MODULES),
+      });
+    });
+
+    afterEach(function () {
+      mockFs.restore();
+      jest.resetModules();
+    });
+
+    it('creates the rule doc including the mandatory section', async function () {
+      await generate('.', {
+        initRuleDocs: true,
+        ruleDocSectionInclude: ['Examples'],
+      });
+      expect(readFileSync('docs/rules/no-foo.md', 'utf8')).toMatchSnapshot();
+      expect(readFileSync('docs/rules/no-bar.md', 'utf8')).toMatchSnapshot(); // Should add options section.
+    });
+  });
+
   describe('no missing rule doc but --init-rule-docs enabled', function () {
     beforeEach(function () {
       mockFs({