build(update-endpoints): generate separate docs/*/*.md files for each endpoint

Author: gr2m

scripts/update-endpoints/docs.js

@@ -1,7 +1,8 @@
-const { readFileSync, writeFileSync } = require("fs");
 const { join } = require("path");
 
+const { outputFileSync } = require("fs-extra");
 const prettier = require("prettier");
+const marked = require("marked");
 
 const ENDPOINTS = require("./generated/endpoints.json");
 const WORKAROUNDS = require("./workarounds");
@@ -13,41 +14,70 @@ const newRoutes = {};
 generateRoutes();
 
 async function generateRoutes() {
-  const examples = ENDPOINTS.concat(WORKAROUNDS)
-    .map(endpoint => {
-      if (endpoint.isLegacy && !/^\/teams\/\{team_id\}/.test(endpoint.url)) {
-        // ignore legacy endpoints with the exception of the new teams legacy methods
-        return;
-      }
-
-      const paramNames = endpoint.parameters
-        .filter(parameter => !parameter.alias)
-        .filter(parameter => !parameter.name.includes("."))
-        .filter(parameter => !["per_page", "page"].includes(parameter.name))
-        .map(parameter => parameter.name)
-        .join(", ");
-
-      const comment = endpoint.renamed
-        ? `// DEPRECATED: octokit.${endpoint.renamed.before.scope}.${endpoint.renamed.before.id}() has been renamed to octokit.${endpoint.renamed.after.scope}.${endpoint.renamed.after.id}()`
-        : `// ${endpoint.documentationUrl}`;
-
-      return `${comment}
-octokit.${endpoint.scope}.${endpoint.id}(${
-        paramNames ? `{ ${paramNames} }` : ""
-      });`;
-    })
-    .join("\n\n");
-
-  const currentContent = readFileSync(README_PATH, "utf8");
-  const newContent = currentContent.replace(
-    /const octokit = new MyOctokit\({ auth: "secret123" }\);[\s\S]*\`/,
-    `const octokit = new MyOctokit({ auth: "secret123" });
-
-${prettier.format(examples, {
-  parser: "babel"
-})}\`\`\``
+  const endpoints = ENDPOINTS.concat(WORKAROUNDS);
+
+  for (const endpoint of endpoints) {
+    const path = `docs/${endpoint.scope}/${endpoint.id}.md`;
+    outputFileSync(path, template(endpoint));
+    console.log(`${path} written`);
+  }
+}
+
+function template(endpoint) {
+  const deprecationNotice = endpoint.isDeprecated
+    ? "**This method is deprecated.**"
+    : "";
+  const renameNotice = endpoint.renamed
+    ? `**Deprecated:** This method has been renamed to ${endpoint.renamed.after.scope}.${endpoint.renamed.after.id}`
+    : "";
+
+  const parameterRows = endpoint.parameters.map(
+    param =>
+      `<tr><td>${param.name}</td><td>${param.required ? "yes" : "no"}</td><td>
+
+${param.description}
+
+</td></tr>`
   );
 
-  writeFileSync(README_PATH, newContent);
-  console.log(`${README_PATH} updated.`);
+  const requiredParameterNames = endpoint.parameters
+    .filter(parameter => parameter.required)
+    .map(parameter => parameter.name);
+  const example = `octokit.${endpoint.scope}.${
+    endpoint.id
+  }(${requiredParameterNames.join(", ")})`;
+
+  const content = `
+# ${endpoint.name}
+
+${deprecationNotice}
+
+${renameNotice}
+
+${endpoint.description}
+
+\`\`\`js
+${example}
+\`\`\`
+
+## Parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>name</th>
+      <th>required</th>
+      <th>description</th>
+    </tr>
+  </thead>
+  <tbody>
+    ${parameterRows.join("\n")}
+  </tbody>
+</table>
+
+See also: [GitHub Developer Guide documentation](endpoint.documentationUrl).`;
+
+  return prettier.format(content, {
+    parser: "markdown"
+  });
 }