docs: refine babel-types docs generator (#13148)

* docs: refine babel-types docs generator

* avoid AST node shape title when it does not have node fields

* remove h1 from the output

* refactor docs generators

packages/babel-types/scripts/generators/docs.js

@@ -5,7 +5,12 @@ import toFunctionName from "../utils/toFunctionName.js";
 import t from "../../lib/index.js";
 
 const readme = [
-  `# @babel/types
+  `---
+id: babel-types
+title: @babel/types
+---
+<!-- Do not modify! This file is automatically generated by
+  github.com/babel/babel/babel-types/scripts/generators/docs.js !-->
 
 > This module contains methods for building ASTs manually and for checking the types of AST nodes.
 
@@ -34,36 +39,39 @@ const customTypes = {
   ObjectProperty: {
     key: "if computed then `Expression` else `Identifier | Literal`",
   },
+  ClassPrivateMethod: {
+    computed: "'false'",
+  },
+  ClassPrivateProperty: {
+    computed: "'false'",
+  },
 };
-Object.keys(t.BUILDER_KEYS)
+const APIHistory = {
-  .sort()
+  ClassProperty: [["v7.6.0", "Supports `static`"]],
-  .forEach(function (key) {
+};
-    readme.push("### " + key[0].toLowerCase() + key.substr(1));
+function formatHistory(historyItems) {
-    readme.push("```javascript");
+  const lines = historyItems.map(
-    readme.push(
+    item => "| `" + item[0] + "` | " + item[1] + " |"
-      "t." + toFunctionName(key) + "(" + t.BUILDER_KEYS[key].join(", ") + ")"
+  );
-    );
+  return [
-    readme.push("```");
+    "<details>",
+    "  <summary>History</summary>",
+    "| Version | Changes |",
+    "| --- | --- |",
+    ...lines,
+    "</details>",
+  ];
+}
+function printAPIHistory(key, readme) {
+  if (APIHistory[key]) {
     readme.push("");
-    readme.push(
+    readme.push(...formatHistory(APIHistory[key]));
-      "See also `t.is" +
+  }
-        key +
+}
-        "(node, opts)` and `t.assert" +
+function printNodeFields(key, readme) {
-        key +
+  if (Object.keys(t.NODE_FIELDS[key]).length > 0) {
-        "(node, opts)`."
-    );
     readme.push("");
-    if (t.ALIAS_KEYS[key] && t.ALIAS_KEYS[key].length) {
+    readme.push("AST Node `" + key + "` shape:");
-      readme.push(
-        "Aliases: " +
-          t.ALIAS_KEYS[key]
-            .map(function (key) {
-              return "`" + key + "`";
-            })
-            .join(", ")
-      );
-      readme.push("");
-    }
     Object.keys(t.NODE_FIELDS[key])
       .sort(function (fieldA, fieldB) {
         const indexA = t.BUILDER_KEYS[key].indexOf(fieldA);
@@ -104,8 +112,47 @@ Object.keys(t.BUILDER_KEYS)
         } else {
           fieldDescription.push(" (required)");
         }
-        readme.push(" - " + fieldDescription.join(""));
+        readme.push("- " + fieldDescription.join(""));
       });
+  }
+}
+
+function printAliasKeys(key, readme) {
+  if (t.ALIAS_KEYS[key] && t.ALIAS_KEYS[key].length) {
+    readme.push("");
+    readme.push(
+      "Aliases: " +
+        t.ALIAS_KEYS[key]
+          .map(function (key) {
+            return "`" + key + "`";
+          })
+          .join(", ")
+    );
+  }
+}
+
+Object.keys(t.BUILDER_KEYS)
+  .sort()
+  .forEach(function (key) {
+    readme.push("### " + toFunctionName(key));
+    readme.push("");
+    readme.push("```javascript");
+    readme.push(
+      "t." + toFunctionName(key) + "(" + t.BUILDER_KEYS[key].join(", ") + ");"
+    );
+    readme.push("```");
+    printAPIHistory(key, readme);
+    readme.push("");
+    readme.push(
+      "See also `t.is" +
+        key +
+        "(node, opts)` and `t.assert" +
+        key +
+        "(node, opts)`."
+    );
+
+    printNodeFields(key, readme);
+    printAliasKeys(key, readme);
 
     readme.push("");
     readme.push("---");