docs: split Operations and Functions into two different lists

OpenFn · Jun 12, 2024 · 61c7556 · 61c7556
1 parent 4d705e0
commit 61c7556
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 19 deletions.
diff --git a/tools/build/src/commands/docs.ts b/tools/build/src/commands/docs.ts
@@ -2,7 +2,7 @@ import fs, { writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import jsdoc2md from 'jsdoc-to-markdown';
-import FileSet from 'file-set'
+import FileSet from 'file-set';
 import resolvePath from '../util/resolve-path';
 import extractExports from '../util/extract-exports';
 
@@ -22,6 +22,19 @@ export default async (lang: string) => {
     files: glob,
   });
 
+  // Identify Operations
+  // TODO we can later add a supporting @operation tag, but this heuristic will go a long way
+  templateData.forEach(doclet => {
+    if (
+      doclet.returns
+        ?.at(0)
+        ?.type?.names.at(0)
+        .match(/operation/i)
+    ) {
+      doclet.kind = 'operation';
+    }
+  });
+
   // sort template data
   // see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
   templateData.sort(function (a, b) {
@@ -37,20 +50,20 @@ export default async (lang: string) => {
     return 0;
   });
 
-  const fileSet = new FileSet()
-  await fileSet.add([glob])
+  const fileSet = new FileSet();
+  await fileSet.add([glob]);
 
   // Extract exports from common and add them to the template data as externals
   for (const f of fileSet.files) {
-    const src = await fs.readFile(f, 'utf8')
-    const exports = extractExports(src).map((e) => ({
+    const src = await fs.readFile(f, 'utf8');
+    const exports = extractExports(src).map(e => ({
       id: e,
       common: true,
       name: e,
       scope: 'global',
-      kind: "external"
-    }))
-    templateData.push(...exports)
+      kind: 'external',
+    }));
+    templateData.push(...exports);
   }
 
   const helper = path.resolve('../../tools/build/src/util/hbs-helpers.js');
@@ -71,7 +84,7 @@ export default async (lang: string) => {
     'example-lang': 'js',
     'member-index-format': 'list',
   };
-  
+
   console.log('rendering jsdocs...');
   const docs = jsdoc2md.renderSync(renderOpts);
 
@@ -114,17 +127,21 @@ export default async (lang: string) => {
     readme: `${JSON.stringify(readme)}`,
     changelog: `${JSON.stringify(changelog)}`,
     functions: functions.sort(),
-    'configuration-schema': configurationSchema
+    'configuration-schema': configurationSchema,
   };
 
   const destinationDir = `${root}/docs`;
   const destination = `${destinationDir}/index.md`;
   await mkdir(destinationDir, { recursive: true });
   await writeFile(destination, docs);
+  await writeFile(
+    `${destinationDir}/raw.json`,
+    JSON.stringify(templateData, null, 2)
+  );
   await writeFile(`${destinationDir}/${lang}.json`, JSON.stringify(docsJson));
 
   console.log(`... done! `, destination);
-  console.log()
+  console.log();
 
   return;
 };
diff --git a/tools/build/src/util/docs-template.hbs b/tools/build/src/util/docs-template.hbs
@@ -1,7 +1,9 @@
 {{#if (showMainIndex)~}}
 
-{{#globals kind="function" ~}}
-{{#if @first~}}## Functions
+{{#globals kind="operation" ~}}
+{{#if @first}}
+
+#### Operations
 
 <dl>
 {{/if~}}
@@ -12,15 +14,37 @@
 {{#if @prefix}}{{@prefix}} {{/if~}}
 {{@accessSymbol}}{{#if (isEvent)}}"{{{name}}}"{{else}}{{{name}}}{{/if~}}
 {{~#if @methodSign}}{{#if (isEvent)}} {{@methodSign}}{{else}}{{@methodSign}}{{/if}}{{/if~}}
-{{{@codeClose}~}}
+{{@codeClose~}}
 </a>
 {{~/sig}}{{/if~}}
 </dt>
 {{!-- <dd>{{{md (inlineLinks description)}}}</dd> --}}
 {{#if @last~}}</dl>
 {{/if~}}
 {{/globals~}}
-{{!-- {{>global-index-kinds kind="typedef" title="Typedefs" ~}} --}}
+
+{{#globals kind="function"}}
+{{#if @first}}
+
+#### Functions
+
+<dl>
+{{/if~}}
+<dt>
+    {{#if name}}{{#sig no-gfm=true ~}}
+<a href="#{{toLowerCase (anchorName)}}">
+{{~{@codeOpen}~}}
+{{#if @prefix}}{{@prefix}} {{/if~}}
+{{@accessSymbol}}{{#if (isEvent)}}"{{{name}}}"{{else}}{{{name}}}{{/if~}}
+{{~#if @methodSign}}{{#if (isEvent)}} {{@methodSign}}{{else}}{{@methodSign}}{{/if}}{{/if~}}
+{{@codeClose~}}
+</a>
+{{~/sig}}{{/if~}}
+</dt>
+{{#if @last~}}</dl>
+{{/if~}}
+{{/globals~}}
+
 {{/if~}}
 
 {{#commonFns}}
@@ -35,14 +59,37 @@ The following functions are exported from the common adaptor:
 {{/if}}
 {{/commonFns}}
 
-{{#orphans ~}}
+{{>separator~}}
+
+{{#globals kind="operation" ~}}
+{{#if @first~}}## Operations
+
+Operations are used at the top level of your job code. You can nest Operations, but you cannot use an Operation within a callback.
+{{/if~}}
+
+### {{anchorName}}
+
+{{! operations should list parameters but not returns }}
+{{>sig-name}}
+
+{{>body}}
+{{>separator~}}
+
+{{/globals~}}
+
+{{#globals kind="function" ~}}
+{{#if @first~}}
+
+## Functions
+
+Functions are regular Javascript functions. They are not state aware, they do not neccessarily take state and they usually don't return state. Functions can only be used inside callback functions.
+{{/if~}}
 
 ### {{anchorName}}
 
 {{>sig-name}}
 
 {{>body}}
-{{>member-index~}}
 {{>separator~}}
-{{>members~}}
-{{/orphans~}}
+
+{{/globals~}}