Extract docs

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug current file",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/babel-node",
+      "runtimeArgs": ["--extensions", ".ts,.tsx,.mjs,.js,.json", "${file}"],
+      "sourceMaps": true,
+      "env": {
+        "BABEL_ENV": "debug"
+      }
+    }
+  ]
+}

package.json

@@ -17,9 +17,15 @@
     "build-consumer": "yarnpkg build && ./scripts/build-consumer.sh",
     "restore-consumer": "./scripts/restore-consumer.sh",
     "clean": "git clean -xdf ./packages; rm -rf ./build",
-    "clear-cache": "rm -rf .sewing-kit"
+    "clear-cache": "rm -rf .sewing-kit",
+    "run:ts": "babel-node --extensions .ts,.tsx,.mjs,.js,.json",
+    "run:ts:watch": "nodemon --ext .ts,.tsx,.mjs,.json,.graphql node_modules/.bin/babel-node --extensions .ts,.tsx,.mjs,.js,.json",
+    "docs:checkout": "babel-node --extensions .ts,.tsx,.mjs,.js,.json scripts/generate-docs-checkout.ts",
+    "docs:admin": "babel-node --extensions .ts,.tsx,.mjs,.js,.json scripts/generate-docs-admin.ts"
   },
   "devDependencies": {
+    "@babel/node": "^7.8.7",
+    "@microsoft/tsdoc": "^0.12.20",
     "@sewing-kit/cli": "^0.2.0",
     "@sewing-kit/config": "^0.1.0",
     "@sewing-kit/eslint-plugin": "^0.0.14",
@@ -30,13 +36,19 @@
     "@sewing-kit/plugin-react": "^0.1.0",
     "@sewing-kit/plugin-typescript": "^0.1.0",
     "@types/execa": "^0.9.0",
+    "@types/resolve": "^1.17.1",
+    "@types/uuid": "^8.3.0",
+    "lerna": "^3.22.1",
+    "markdown-table": "^2.0.0",
+    "nodemon": "^2.0.4",
     "react": ">=17.0.0 <18.0.0",
-    "lerna": "^3.22.1"
+    "resolve": "^1.17.0",
+    "uuid": "^8.3.2"
   },
   "resolutions": {
     "@typescript-eslint/eslint-plugin": "^4.0.0",
     "@typescript-eslint/experimental-utils": "^4.0.0",
     "@typescript-eslint/parser": "^4.0.0",
     "typescript": "^4.1.0"
   }
-}
+}

scripts/.babelrc

@@ -0,0 +1,12 @@
+{
+  "presets": [
+    ["@babel/preset-env", {"targets": {"node": true}}],
+    "@babel/preset-typescript"
+  ],
+  "env": {
+    "debug": {
+      "sourceMaps": "inline",
+      "retainLines": true
+    }
+  }
+}

scripts/generate-docs-admin.ts

@@ -0,0 +1,14 @@
+import {components, extensionPoints} from './typedoc/shopify-dev-renderer';
+
+const paths = {
+  inputRoot: './packages/argo-admin',
+  packages: {
+    JavaScript: './packages/argo-admin',
+    React: './packages/argo-admin-react',
+  },
+  outputRoot: '../shopify-dev/content/tools/argo-admin',
+  shopifyDevUrl: '/tools/argo-admin',
+};
+
+components(paths);
+extensionPoints(paths);

scripts/generate-docs-checkout.ts

@@ -0,0 +1,13 @@
+import {renderForShopifyDev} from './typedoc';
+
+const paths = {
+  inputRoot: '../checkout-web/packages/argo-checkout',
+  packages: {
+    JS: '../checkout-web/packages/argo-checkout',
+    React: '../checkout-web/packages/argo-checkout-react',
+  },
+  outputRoot: '../shopify-dev/content/docs/checkout-extensions',
+  shopifyDevUrl: '/docs/checkout-extensions',
+};
+
+renderForShopifyDev(paths);

scripts/typedoc/index.ts

@@ -0,0 +1 @@
+export {renderForShopifyDev} from './shopify-dev-renderer';

scripts/typedoc/shopify-dev-renderer/components.ts

@@ -0,0 +1,196 @@
+import {resolve, extname} from 'path';
+import * as fs from 'fs';
+
+import type {
+  Paths,
+  Packages,
+} from '../types';
+
+import {createDependencyGraph} from '../utilities/dependency-graph';
+
+import {renderYamlFrontMatter, findUuid, dedupe, propsTable, strip, firstSentence} from './shared';
+import type {Node} from './shared';
+
+const additionalPropsTables: string[] = [];
+
+export async function components(paths: Paths) {
+  const componentIndex = resolve(`${paths.inputRoot}/src/components/index.ts`);
+  const {nodes, components} = await buildComponentGraph(componentIndex);
+
+  const outputRoot = resolve(`${paths.outputRoot}`);
+  const componentDocsPath = resolve(`${paths.outputRoot}/components`);
+
+  if (!fs.existsSync(outputRoot)) {
+    fs.mkdirSync(outputRoot);
+  }
+
+  if (!fs.existsSync(componentDocsPath)) {
+    fs.mkdirSync(componentDocsPath);
+  }
+
+  const indexFile = resolve(`${paths.outputRoot}/components/index.md`);
+  let index = renderYamlFrontMatter({
+    gid: findUuid(indexFile),
+    url: `${paths.shopifyDevUrl}/components/index`,
+    title: 'Components for checkout extensions',
+    description: 'A list of components for checkout extensions.',
+    hidden: true,
+  });
+
+  index += `Argo provides many powerful UI components that a
+  [rendering extension](${paths.shopifyDevUrl}/extension-points#rendering) can
+  use to build an interface. This UI is rendered natively by Shopify, so you
+  can depend on it to be performant, accessible, and work in all of Checkout’s
+  supported browsers. \n\nThe following components are available as part of Argo
+  for Checkout, but make sure that you check the documentation for your
+  [extension point](${paths.shopifyDevUrl}/extension-points#extension-points)
+  to ensure the component is available in the extension points you are
+  targeting.\n\n`;
+
+  index += '<ul style="column-count: auto;column-width: 12rem;">';
+
+  components.forEach(({value: {name, docs, props}}: any) => {
+    const outputFile = `${componentDocsPath}/${name.toLowerCase()}.md`;
+
+    const docsContent = docs ? strip(docs.content).trim() : '';
+
+    const componentUrl = `${
+      paths.shopifyDevUrl
+    }/components/${name.toLowerCase()}`;
+
+    let markdown = renderYamlFrontMatter({
+      gid: findUuid(outputFile),
+      url: componentUrl,
+      title: `${name}`,
+      description: `"${firstSentence(docsContent)}"`,
+      hidden: true,
+    });
+    markdown += docsContent ? `${docsContent}\n\n` : '';
+
+    const examples = renderComponentExamplesFor(name, paths.packages);
+    if (examples.length > 0) {
+      markdown += examples;
+    }
+
+    const face = nodes.find(({value}: any) => value.name === props.name);
+    if (
+      face &&
+      face.value.kind === 'InterfaceType' &&
+      face.value.properties.length > 0
+    ) {
+      markdown += '## Props\noptional = ?\n';
+      markdown += propsTable(
+        name,
+        docs,
+        face.value.properties,
+        nodes,
+        componentIndex,
+        additionalPropsTables,
+        false,
+        undefined,
+      );
+    }
+
+    markdown += dedupe(additionalPropsTables).reverse().join('');
+
+    const contentFolder = resolve(
+      `${paths.inputRoot}/src/components/${name}/content`,
+    );
+    markdown += getAdditionalContentFor(contentFolder);
+
+    fs.writeFile(outputFile, markdown, function (err) {
+      if (err) throw err;
+    });
+
+    additionalPropsTables.length = 0;
+    index += `<li><a href="${componentUrl}">${name}</a></li>`;
+  });
+
+  index += '</ul>';
+
+  // Write the component table of contents
+  fs.writeFile(indexFile, index, function (err) {
+    if (err) throw err;
+  });
+}
+
+async function buildComponentGraph(componentIndex: string) {
+  const graph = await createDependencyGraph(componentIndex);
+
+  const nodes: Node[] = [];
+
+  graph.forEach((value) => {
+    value.locals.forEach((value: any, key) => {
+      if (value.kind !== 'Imported') {
+        if (value.name == null) {
+          value.name = key;
+        }
+        nodes.push({value, module: undefined});
+      }
+    });
+  });
+
+  const components = [
+    ...new Set(nodes.filter(({value}: any) => value.kind === 'Component')),
+  ];
+
+  // console.log(JSON.stringify(nodes))
+
+  // Sort alphabetically (tsdoc seems to get this confused)
+  components.sort((aa: any, bb: any) => {
+    if (aa.value.name > bb.value.name) {
+      return 1;
+    } else if (aa.value.name < bb.value.name) {
+      return -1;
+    } else {
+      return 0;
+    }
+  });
+
+  return {nodes, components};
+}
+
+function renderComponentExamplesFor(name: string, packages: Packages): string {
+  const examples: any = {};
+
+  Object.keys(packages).forEach((packageName) => {
+    const packagePath = packages[packageName];
+    const folder = resolve(`${packagePath}/src/components/${name}/examples`);
+
+    if (fs.existsSync(folder)) {
+      fs.readdirSync(folder).forEach((file) => {
+        const extension = extname(file).split('.').pop();
+        examples[packageName] = `{% highlight ${extension} %}{% raw %}\n`;
+        examples[packageName] += fs.readFileSync(`${folder}/${file}`, 'utf8');
+        examples[packageName] += '\n{% endraw %}{% endhighlight %}\n\n';
+      });
+    }
+  });
+
+  let markdown = '';
+
+  const exampleCount = Object.keys(examples).length;
+
+  if (exampleCount > 1) {
+    const sections = Object.keys(examples).join(', ');
+    markdown += `{% sections "${sections}" %}\n\n`;
+    markdown += Object.values(examples).join('\n\n----\n\n');
+    markdown += '{% endsections %}\n\n';
+  } else if (exampleCount > 0) {
+    markdown += Object.values(examples).join('\n\n----\n\n');
+  }
+
+  return markdown;
+}
+
+function getAdditionalContentFor(contentFolder: string) {
+  let markdown = '';
+
+  if (fs.existsSync(contentFolder)) {
+    fs.readdirSync(contentFolder).forEach((file) => {
+      markdown += fs.readFileSync(`${contentFolder}/${file}`, 'utf8');
+    });
+  }
+
+  return markdown;
+}

scripts/typedoc/shopify-dev-renderer/extension-points.ts

@@ -0,0 +1,90 @@
+import {resolve} from 'path';
+import * as fs from 'fs';
+
+import type {
+  Paths,
+  InterfaceType,
+} from '../types';
+
+import {createDependencyGraph} from '../utilities/dependency-graph';
+import {renderYamlFrontMatter, findUuid, dedupe, propsTable} from './shared';
+import type {Node} from './shared';
+
+const additionalPropsTables: string[] = [];
+
+export async function extensionPoints(paths: Paths) {
+  const extensionsIndex = resolve(`${paths.inputRoot}/src/index.ts`);
+
+  const graph = await createDependencyGraph(extensionsIndex);
+
+  const allInterfaces: InterfaceType[] = [];
+
+  for (const value of graph.values()) {
+    const localValues = [...value.locals.values()];
+    allInterfaces.push(
+      ...(localValues.filter(
+        ({kind}) => kind === 'InterfaceType',
+      ) as InterfaceType[]),
+    );
+  }
+
+  const nodes: Node[] = [];
+
+  graph.forEach((value) => {
+    value.locals.forEach((value: any, key) => {
+      if (value.kind !== 'Imported') {
+        if (value.name == null) {
+          value.name = key;
+        }
+        nodes.push({value, module: undefined});
+      }
+    });
+  });
+
+  const interfaceEntryPoints = ['ExtensionPoints'];
+
+  const interfaces = allInterfaces.filter(({name}) =>
+    interfaceEntryPoints.includes(name),
+  );
+
+  const rootFolder = resolve(paths.outputRoot)
+  if (!fs.existsSync(rootFolder)) {
+    fs.mkdirSync(rootFolder);
+  }
+
+  const folder = resolve(`${paths.outputRoot}/extension-points`);
+  if (!fs.existsSync(folder)) {
+    fs.mkdirSync(folder);
+  }
+
+  const apiFile = resolve(`${paths.outputRoot}/extension-points/api.md`);
+
+  let markdown = renderYamlFrontMatter({
+    gid: findUuid(apiFile),
+    url: `${paths.shopifyDevUrl}/extension-points/api`,
+    title: 'Extension points API',
+    hidden: true,
+  });
+
+  interfaces.forEach(({name, docs, properties}) => {
+    markdown += propsTable(
+      name,
+      docs,
+      properties,
+      nodes,
+      extensionsIndex,
+      additionalPropsTables,
+      undefined,
+      undefined,
+    );
+  });
+
+  markdown += dedupe(additionalPropsTables).reverse().join('');
+
+  fs.writeFile(apiFile, markdown, function (err) {
+    if (err) throw err;
+  });
+
+  additionalPropsTables.length = 0;
+}
+