Merge pull request linode#132 from alioso/hand-off-documentation

alioso · web-flow · commit 1f39aa1d728a · 2019-12-26T11:45:35.000-05:00
Hand off documentation
diff --git a/README.md b/README.md
@@ -4,6 +4,8 @@ The developers.linode.com website built with Gatsby and including the API Docs
 
 ## Setup
 
+DLC currently needs `node v10.16.0` to build properly. You may want to use NVM to manage your versions (https://github.com/nvm-sh/nvm/blob/master/README.md)
+
 `yarn`
 
 `yarn develop`
diff --git a/gatsby-node.js b/gatsby-node.js
@@ -12,9 +12,15 @@ const { recursiveQuery } = require("./generateQuery.js");
 
 exports.sourceNodes = async ({ actions }) => {
   const { createNode, createTypes } = actions;
+
+  // This parser allows compiling the JSON object into a valid
+  // OpenAPI object (parsing $refs etc)
   const res = await parser.dereference(specs);
 
   // CREATING NODES FROM API SPECS
+
+  // Type definitions for GraphQL
+  // We force define these types to avoid build errors
   const typeDefs = `
     type MarkdownRemark implements Node {
       frontmatter: Frontmatter!
@@ -29,15 +35,15 @@ exports.sourceNodes = async ({ actions }) => {
   createTypes(typeDefs);
 
   const allSpecs =
-    // map into these results and create nodes
+    // crate endpoint smap
     Object.keys(res.paths).map(async (path, i) => {
       // Create your node object
       const pathNode = {
         // Required fields
         id: `${i}`,
         parent: `__SOURCE__`,
         internal: {
-          type: `Paths` // name of the graphQL query --> allRandomUser {}
+          type: `Paths` // name of the graphQL query --> allPaths {}
         },
         children: [],
 
@@ -69,10 +75,9 @@ exports.sourceNodes = async ({ actions }) => {
       createNode(pathNode);
     });
 
-  const baseUrl =
-    "https://linode.com/wp-json/menus/v1/menus";
-
   // CREATING MENU NODES FROM WP API
+  // This will gather the WP API from linode.com to build the header menu items
+  const baseUrl = "https://linode.com/wp-json/menus/v1/menus";
   const wpMenus = [
     {
       path: `${baseUrl}/header-utility`,
@@ -170,6 +175,7 @@ exports.sourceNodes = async ({ actions }) => {
   return Promise.all(allMenus, allSpecs);
 };
 
+// GENERATE CHANGELOG ENTRIES
 exports.createPages = async ({ actions, graphql }) => {
   const { createPage } = actions;
   const changelogTemplate = path.resolve(
@@ -207,7 +213,7 @@ exports.createPages = async ({ actions, graphql }) => {
     // Eliminate duplicate tags
     tags = _.uniq(tags);
 
-    // Make tag pages
+    // Make changelog pages
     tags.forEach(changelog => {
       createPage({
         path: `/changelog/${_.kebabCase(changelog)}/`,
@@ -253,6 +259,7 @@ exports.createPages = async ({ actions, graphql }) => {
     });
   });
 
+  // CREATE FRAGMENTS
   const fragmentQueries = [
     {
       path: "PathsGetResponses_200ContentApplication_jsonSchemaProperties",
@@ -286,6 +293,9 @@ exports.createPages = async ({ actions, graphql }) => {
 
   const fragments = [];
 
+  // GraphQL introspection query
+  // Not sure if there's a better way top generate a recursive pattern here,
+  // but this code makes sure we good deep enough into the data
   await fragmentQueries.map(q => {
     let partialFragments = graphql(`
     {
@@ -688,6 +698,7 @@ exports.createPages = async ({ actions, graphql }) => {
         .toString()
         .replace(/\,/g, "");
 
+      // Write REACT files for each fragment
       return (
         fragments.push(partialFragments),
         file.write(`
diff --git a/postcss.config.js b/postcss.config.js
@@ -9,6 +9,10 @@ class TailwindExtractor {
   }
 }
 
+// The css setup uses TailwindCSS as a utility library (https://tailwindcss.com/#what-is-tailwind).
+// We imports tailwind, then purge CSS classes that are not used
+// See gatsby-config.js for details
+
 module.exports = {
   plugins: [
     atImport,
diff --git a/src/components/2_molecules/ResponseItemElements.js b/src/components/2_molecules/ResponseItemElements.js
@@ -8,6 +8,12 @@ import Nullable from "./Nullable";
 import SubResponse from "./SubResponse";
 import CharDisplay from "./charDisplay";
 
+/* 
+  __TODO__ needs better scripting. 
+  Ideally we should generate this in a much more dynamic way
+  We are missing data at times, and missing deeply nested data.
+*/
+
 export const ResponseItemElements = props => {
   const { context } = props;
   return (
@@ -23,7 +29,6 @@ export const ResponseItemElements = props => {
           )
           .map((p, i) => {
             const l = context.content.application_json.schema.properties[p];
-            // console.log(l);
             return (
               l && (
                 <div key={i} className="response-wrapper">
@@ -71,7 +76,6 @@ export const ResponseItemElements = props => {
                           Object.keys(l.items.properties).map(
                             (value, index) => {
                               const data = l.items.properties[value];
-                              // console.log(data);
                               return (
                                 data && (
                                   <div key={index} className="response-wrapper">
diff --git a/src/components/2_molecules/ResponseSample.js b/src/components/2_molecules/ResponseSample.js
@@ -2,6 +2,12 @@ import React from "react";
 import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { atomDark } from "react-syntax-highlighter/dist/esm/styles/prism";
 
+/* 
+  __TODO__ needs better scripting. 
+  Ideally we should generate this in a much more dynamic way
+  We are missing data at times, and missing deeply nested data.
+*/
+
 export const ResponseItem = props => {
   const { response, r } = props;
   return (
@@ -62,42 +68,41 @@ export const ResponseItem = props => {
                               </div>
                             );
                           })}
-                        {l.items &&
-                          (l.items.properties && (
-                            <div>
-                              {"  {"}
-                              {Object.keys(l.items.properties).map((e, i) => {
-                                const data = l.items.properties[e];
-                                const rowLen3 = Object.keys(l.items).length;
-                                return (
-                                  data && (
-                                    <div key={i} className="ml-8">
-                                      <div>
-                                        "{e}":{" "}
-                                        <span style={{ color: "#3BB878" }}>
-                                          "{data.example}"
-                                          {rowLen3 === i + 1 && ","}
-                                        </span>
-                                      </div>
+                        {l.items && l.items.properties && (
+                          <div>
+                            {"  {"}
+                            {Object.keys(l.items.properties).map((e, i) => {
+                              const data = l.items.properties[e];
+                              const rowLen3 = Object.keys(l.items).length;
+                              return (
+                                data && (
+                                  <div key={i} className="ml-8">
+                                    <div>
+                                      "{e}":{" "}
+                                      <span style={{ color: "#3BB878" }}>
+                                        "{data.example}"
+                                        {rowLen3 === i + 1 && ","}
+                                      </span>
                                     </div>
-                                  )
-                                );
-                              })}
-                              {"  }"}
-                              {l.type !== "array" && (
-                                <div>
-                                  {"]"}
-                                  {rowLen !== i + 1 && ","}
-                                </div>
-                              )}
-                              {p !== "errors" && (
-                                <div>
-                                  {"]"}
-                                  {rowLen !== i + 1 && ","}
-                                </div>
-                              )}
-                            </div>
-                          ))}
+                                  </div>
+                                )
+                              );
+                            })}
+                            {"  }"}
+                            {l.type !== "array" && (
+                              <div>
+                                {"]"}
+                                {rowLen !== i + 1 && ","}
+                              </div>
+                            )}
+                            {p !== "errors" && (
+                              <div>
+                                {"]"}
+                                {rowLen !== i + 1 && ","}
+                              </div>
+                            )}
+                          </div>
+                        )}
                       </div>
                     )
                   );
diff --git a/src/components/2_molecules/ResponseSampleBody.js b/src/components/2_molecules/ResponseSampleBody.js
@@ -12,14 +12,23 @@ export const ResponseSampleBody = props => {
     context
   );
 
+  {
+    /* 
+      __TODO__ Sample source need better scripting. 
+      Kinda hand coded for speed, not very scalable and missing info.
+      Ideally we should generate this in a much more dynamic way
+      We are missing data at times, and missing deeply nested data.
+      Additionally, allOf & oneOf need better handling
+    */
+  }
+
   const sampleSource = `
       {
       ${properties &&
         Object.keys(properties)
           .filter(v => properties[v] !== null)
           .map(p => {
             const l = properties[p];
-            // console.log(l);
             return (
               l &&
               (l.type !== "array" && p !== "errors" && l.type !== "object"
@@ -120,9 +129,9 @@ export const ResponseSampleBody = props => {
                     .map(e => {
                       const data = l.items.properties[e];
                       return data &&
-                        (data.type !== "array" &&
-                          data.type !== "object" &&
-                          !data.oneOf)
+                        data.type !== "array" &&
+                        data.type !== "object" &&
+                        !data.oneOf
                         ? `
                         "${e}": ${JSON.stringify(
                             data.example ? data.example : ""
@@ -138,7 +147,8 @@ export const ResponseSampleBody = props => {
                                 .map(oo => {
                                   const ro = o.properties[oo];
                                   return ro &&
-                                    (ro.type === "object" && ro.properties)
+                                    ro.type === "object" &&
+                                    ro.properties
                                     ? `"${oo}": {
                                       ${Object.keys(ro.properties)
                                         .filter(
@@ -214,6 +224,9 @@ export const ResponseSampleBody = props => {
     console.log(e);
   }
 
+  // Switch constants for testing if data does not show up for instance
+  // `sanitized` will output unformatted data to test it
+
   const finalSource = JSON.stringify(parsed, null, 2);
   // const finalSource = sanitized;
 
diff --git a/src/components/2_molecules/ResponseSamples.js b/src/components/2_molecules/ResponseSamples.js
@@ -32,6 +32,7 @@ export const ResponseSamples = props => {
           return (
             response !== null && (
               <TabPanel key={i}>
+                {/* __TODO__ This below needs work. Logic is not sound */}
                 {(mode === "put" || mode === "post") && response["default"] ? (
                   <ResponseSampleBody
                     response={options[e]}
diff --git a/src/components/2_molecules/allOf.js b/src/components/2_molecules/allOf.js
@@ -1,3 +1,10 @@
+/* 
+  __TODO__ May need rework
+  1. We worked out what allOfs and oneOfs are supposed to do, but did not get a chance to get to it
+     This component has more complexion we need to address
+  2. We need to handle more recursion here, deep nested data may not show
+*/
+
 const accumulator = (or, ov) => {
   return Object.keys(or).reduce((acc, currentKey) => {
     if (!!ov[currentKey]) {
diff --git a/tailwind.js b/tailwind.js
@@ -1,5 +1,7 @@
+// We import the tailwind settings from the base theme
 const config = require("./linode-hugo-theme/tailwind");
 
+// We override (merge) or add specific settings to DLC
 config.colors["ThemeCell"] = "#f4f4f4";
 config.colors["ThemeBeige"] = "#eCeCeC";
 config.colors["ThemeTagGrey"] = "#e1e8eC";

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,10 @@ class TailwindExtractor {`
`9`	`9`	`}`
`10`	`10`	`}`
`11`	`11`
	`12`	`+// The css setup uses TailwindCSS as a utility library (https://tailwindcss.com/#what-is-tailwind).`
	`13`	`+// We imports tailwind, then purge CSS classes that are not used`
	`14`	`+// See gatsby-config.js for details`
	`15`	`+`
`12`	`16`	`module.exports = {`
`13`	`17`	`plugins: [`
`14`	`18`	`atImport,`