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
babel · Apr 14, 2021 · d6d942d · d6d942d
1 parent 1e31d41
commit d6d942d
Showing 1 changed file with 76 additions and 29 deletions.
diff --git a/packages/babel-types/scripts/generators/docs.js b/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)
-  .sort()
-  .forEach(function (key) {
-    readme.push("### " + key[0].toLowerCase() + key.substr(1));
-    readme.push("```javascript");
-    readme.push(
-      "t." + toFunctionName(key) + "(" + t.BUILDER_KEYS[key].join(", ") + ")"
-    );
-    readme.push("```");
+const APIHistory = {
+  ClassProperty: [["v7.6.0", "Supports `static`"]],
+};
+function formatHistory(historyItems) {
+  const lines = historyItems.map(
+    item => "| `" + item[0] + "` | " + item[1] + " |"
+  );
+  return [
+    "<details>",
+    "  <summary>History</summary>",
+    "| Version | Changes |",
+    "| --- | --- |",
+    ...lines,
+    "</details>",
+  ];
+}
+function printAPIHistory(key, readme) {
+  if (APIHistory[key]) {
     readme.push("");
-    readme.push(
-      "See also `t.is" +
-        key +
-        "(node, opts)` and `t.assert" +
-        key +
-        "(node, opts)`."
-    );
+    readme.push(...formatHistory(APIHistory[key]));
+  }
+}
+function printNodeFields(key, readme) {
+  if (Object.keys(t.NODE_FIELDS[key]).length > 0) {
     readme.push("");
-    if (t.ALIAS_KEYS[key] && t.ALIAS_KEYS[key].length) {
-      readme.push(
-        "Aliases: " +
-          t.ALIAS_KEYS[key]
-            .map(function (key) {
-              return "`" + key + "`";
-            })
-            .join(", ")
-      );
-      readme.push("");
-    }
+    readme.push("AST Node `" + key + "` shape:");
     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("---");