docs: split Operations and Functions into two different lists

OpenFn · Jun 24, 2024 · bb70f54 · bb70f54
1 parent 4975d39
commit bb70f54
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 8 deletions.
diff --git a/tools/build/src/commands/docs.ts b/tools/build/src/commands/docs.ts
@@ -48,6 +48,19 @@ const build = async (lang: string) => {
     'no-cache': true,
   });
 
+  // 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) {
@@ -148,6 +161,10 @@ const build = async (lang: string) => {
   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));
 
   await writeFile(

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~}}