Merge pull request #465 from open-rpc/feat/docs

feat: add docs generator

.gitignore

@@ -4,7 +4,6 @@
 **/docs
 **/.idea
 coverage
-docs
 .DS_Store
 test
 generated

src/cli.ts

@@ -45,8 +45,18 @@ program
         choices: [
           { name: "client" },
           { name: "server" },
+          { name: "docs" },
         ]
       },
+      {
+        name: "docsLanguages",
+        type: "checkbox",
+        message: "What type of documentation do you want to generate?",
+        choices: [
+          { name: "gatsby" }
+        ],
+        when: (answers: any) => answers.componentTypes && answers.componentTypes.find((ct: string) => ct === "docs") !== undefined
+      },
       {
         name: "clientLanguages",
         type: "checkbox",
@@ -66,6 +76,12 @@ program
         ],
         when: (answers: any) => answers.componentTypes && answers.componentTypes.find((ct: string) => ct === "server") !== undefined
       },
+      {
+        name: "gatsbyDocsName",
+        type: "input",
+        message: "What would you like the gatsby based docs package to be named?",
+        when: (answers: any) => answers.clientLanguages && answers.clientLanguages.find((ct: string) => ct === "typescript") !== undefined
+      },
       {
         name: "typescriptClientName",
         type: "input",

src/components/docs.ts

@@ -0,0 +1,139 @@
+import * as path from "path";
+import { move, ensureDir, remove } from "fs-extra";
+import { IHooks } from "..";
+import * as fs from "fs";
+import { promisify } from "util";
+import { template, startCase } from "lodash";
+import { ContentDescriptorObject, ExamplePairingObject, ExampleObject, MethodObject } from "@open-rpc/meta-schema";
+const writeFile = promisify(fs.writeFile);
+const readFile = promisify(fs.readFile);
+const access = promisify(fs.access);
+
+const indexTemplate = template(`import React, { useEffect } from "react";
+import { Grid, Typography, Box, Button } from "@material-ui/core";
+import { Link as GatsbyLink } from "gatsby";
+import Link from "@material-ui/core/Link";
+import { grey } from "@material-ui/core/colors";
+
+const MyApp: React.FC = () => {
+  return (
+    <>
+      <Grid container alignContent="center" alignItems="center" justify="center" direction="column">
+        <img className="logo" alt="logo" src={"https://raw.githubusercontent.com/open-rpc/design/master/icons/open-rpc-logo-noText/open-rpc-logo-noText%20(PNG)/256x256.png"} style={{ paddingTop: "10%" }} />
+        <br/>
+        <Typography variant="h1"><%= openrpcDocument.info.title %></Typography>
+        <Typography gutterBottom style={{ paddingTop: "100px", paddingBottom: "20px" }} variant="inherit">
+          <%= openrpcDocument.info.description %>
+        </Typography>
+        <br/>
+        <Button variant="contained" color="primary" href="/api-documentation">
+          API Reference Documentation
+        </Button>
+        <br />
+        <br />
+        <br />
+      </Grid>
+    </>
+  );
+};
+
+export default MyApp;
+`);
+
+const gatsbyConfigTemplate = template(`
+module.exports = {
+  pathPrefix: "",
+  siteMetadata: {
+    title: '<%= openrpcDocument.info.title %>',
+    description: '<%= openrpcDocument.info.description %>',
+    logoUrl: 'https://raw.githubusercontent.com/open-rpc/design/master/icons/open-rpc-logo-noText/open-rpc-logo-noText%20(PNG)/256x256.png',
+    primaryColor: '#3f51b5', //material-ui primary color
+    secondaryColor: '#f50057', //material-ui secondary color
+    author: '',
+    menuLinks: [
+      {
+        name: 'home',
+        link: '/',
+        ignoreNextPrev: true
+      },
+      {
+        name: 'API Documentation',
+        link: '/api-documentation'
+      }
+    ],
+    footerLinks: [
+      {
+        name: 'OpenRPC',
+        link: 'https://open-rpc.org'
+      }
+    ]
+  },
+  plugins: [
+    "@xops.net/gatsby-openrpc-theme",
+    {
+      resolve: 'gatsby-plugin-manifest',
+      options: {
+        name: 'pristine-site',
+        short_name: 'pristine-site',
+        start_url: '/',
+        background_color: 'transparent',
+        theme_color: '#3f51b5',
+        display: 'minimal-ui',
+        icon: 'src/images/gatsby-icon.png', // This path is relative to the root of the site.
+      },
+    }
+  ],
+}
+`);
+
+const hooks: IHooks = {
+  afterCopyStatic: [
+    async (dest, frm, component, openrpcDocument) => {
+      const destPath = path.join(dest, "package.json");
+      const tmplPath = path.join(dest, "_package.json");
+
+      const tmplPkgStr = await readFile(tmplPath, "utf8");
+      let tmplPkg = JSON.parse(tmplPkgStr);
+
+      tmplPkg.name = component.name || startCase(openrpcDocument.info.title).replace(/\s/g, "");
+      tmplPkg.version = openrpcDocument.info.version;
+
+      let currPkgStr;
+      try {
+        currPkgStr = await readFile(destPath, "utf8");
+        const currPkg = JSON.parse(currPkgStr);
+        tmplPkg = {
+          ...currPkg,
+          ...tmplPkg,
+          dependencies: {
+            ...currPkg.dependencies,
+            ...tmplPkg.dependencies,
+          },
+          devDependencies: {
+            ...currPkg.devDependencies,
+            ...tmplPkg.devDependencies,
+          },
+        };
+      } catch (e) {
+        // do nothing
+      }
+
+      await writeFile(destPath, JSON.stringify(tmplPkg, undefined, "  "));
+      await remove(tmplPath);
+    },
+  ],
+  templateFiles: {
+    gatsby: [
+      {
+        path: "src/pages/index.tsx",
+        template: indexTemplate,
+      },
+      {
+        path: "gatsby-config.js",
+        template: gatsbyConfigTemplate,
+      },
+    ],
+  },
+};
+
+export default hooks;

src/index.test.ts

@@ -76,6 +76,7 @@ describe(`Examples to generate Js clients`, () => {
           { type: "client", language: "rust", name: "testclient-rs" },
           { type: "client", language: "typescript", name: "testclient-ts" },
           { type: "server", language: "typescript", name: "testserver-ts" },
+          { type: "docs", language: "gatsby", name: "testserver-gatsby" },
         ],
       });
 
@@ -88,6 +89,7 @@ describe(`Examples to generate Js clients`, () => {
           { type: "client", language: "rust", name: "testclient-rs" },
           { type: "client", language: "typescript", name: "testclient-ts" },
           { type: "server", language: "typescript", name: "testserver-ts" },
+          { type: "docs", language: "gatsby", name: "testserver-gatsby" },
         ],
       });
 

src/index.ts

@@ -10,6 +10,7 @@ import MethodTypings from "@open-rpc/typings";
 
 import clientComponent from "./components/client";
 import serverComponent from "./components/server";
+import docsComponent from "./components/docs";
 
 const writeFile = promisify(fs.writeFile);
 
@@ -49,6 +50,7 @@ interface IComponentHooks {
 const componentHooks: IComponentHooks = {
   client: clientComponent,
   server: serverComponent,
+  docs: docsComponent,
 };
 
 const getComponentTemplatePath = (component: TComponentConfig) => {
@@ -113,7 +115,13 @@ interface IServerConfig {
   language: "typescript";
 }
 
-type TComponentConfig = IClientConfig | IServerConfig;
+interface IDocsConfig {
+  type: "docs";
+  name: string;
+  language: "gatsby";
+}
+
+type TComponentConfig = IClientConfig | IServerConfig | IDocsConfig;
 
 export interface IGeneratorOptions {
   outDir: string;

templates/docs/gatsby/BUILDING.md

@@ -0,0 +1,18 @@
+# Building
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
+
+This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+
+## Dependencies
+
+- [graphviz](https://graphviz.gitlab.io/download/)
+- [svgbob](https://github.com/ivanceras/svgbob)
+
+
+
+## How to build for production
+
+`npm run build`
+
+and you can statically serve the `public/` folder.