Merge pull request #217 from laverya/update-docs-generation

make the generated docs be closer to the currently published docs
replicatedhq · Jul 31, 2018 · c7c6476 · c7c6476
2 parents ac098b2 + 94d0975
commit c7c6476
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 7 deletions.
diff --git a/hack/docs/mutations.json b/hack/docs/mutations.json
@@ -399,6 +399,12 @@
       "description": "Content type of the body sent with a `POST` request"
     }
   },
+  {
+    "path": "properties.assets.properties.v1.items.properties.web.properties.dest",
+    "merge": {
+      "description": "A path to which the file should be written when generating assets"
+    }
+  },
   {
     "path": "properties.assets.properties.v1.items.properties.web.properties.url",
     "merge": {

diff --git a/hack/docs/schema.json b/hack/docs/schema.json
@@ -522,6 +522,7 @@
                     "type": "string"
                   },
                   "dest": {
+                    "description": "A path to which the file should be written when generating assets",
                     "type": "string"
                   },
                   "headers": {

diff --git a/hack/docs/src/markdown.ts b/hack/docs/src/markdown.ts
@@ -21,7 +21,7 @@ function maybeRenderParameters(paramType, param: any[], typeOf) {
   let doc = "";
   if (param.length !== 0) {
     doc += `
-    
+
 ### ${typeOf} Parameters
 
 `;
@@ -39,7 +39,7 @@ function maybeRenderParameters(paramType, param: any[], typeOf) {
 `;
         for (const childDescr of requiredSubParam) {
           doc += `
-    - ${"`" + childDescr.field + "`"} - ${childDescr.description}
+  - ${"`" + childDescr.field + "`"} - ${childDescr.description}
 `;
         }
       }
@@ -49,7 +49,7 @@ function maybeRenderParameters(paramType, param: any[], typeOf) {
 `;
         for (const childDescr of optionalSubParam) {
           doc += `
-    - ${"`" + childDescr.field + "`"} - ${childDescr.description}
+  - ${"`" + childDescr.field + "`"} - ${childDescr.description}
 `;
         }
       }
@@ -129,6 +129,9 @@ function parseSubParameters(paramType: any, spec: string) {
 function maybeRenderExamples(specTypes: any, specType, subgroup: string) {
   let doc = "";
   if (specTypes[specType].examples) {
+    doc += `
+### Examples
+`;
     for (const example of specTypes[specType].examples) {
       console.log("EXAMPLE", subgroup, specType);
       doc += `
@@ -181,7 +184,6 @@ export const handler = (argv) => {
 
       let doc = "";
       doc += writeHeader(specTypes, specType, subgroup);
-      doc += maybeRenderExamples(specTypes, specType, subgroup);
 
       const {required, optional} = parseParameters(specTypes, specType);
 
@@ -190,9 +192,7 @@ export const handler = (argv) => {
       doc += maybeRenderParameters(subTypes, required, `Required`);
       doc += maybeRenderParameters(subTypes, optional, `Optional`);
 
-      doc += `
-    
-    `;
+      doc += maybeRenderExamples(specTypes, specType, subgroup);
 
       fs.writeFileSync(`${subgroup}/${cleanProperty}.md`, doc);
     }