Merge pull request #459 from OpenFn/http-docs

HTTP: Improve docs

README.md

@@ -291,6 +291,25 @@ Examples:
 pnpm -C packages/salesforce build --watch
 ```
 
+### Docs
+
+Docs are generated from the JSDoc annotations in adaptors. They are output as
+markdown files in the `./docs` directly and not checked in to source control.
+
+The markdown output can be customised by overriding the built-in handlebars
+templates in jsoc2md.
+
+- Find the template you want to customise in [j2sdoc2md source()
+  https://github.com/jsdoc2md/dmd/tree/master/partials) (this can be tricky)
+- Copy the template contents
+- Paste into a file with the same name (this is important) in
+  `tools/build/src/partials`
+- Edit `tools/build/src/commands/docs.ts` and add the path to your new template
+  to jsdoc2md's `renderOpts` (see how the other .hbs files are loaded in)
+- Make your changes
+- Run `pnpm build docs` from root (or just one adaptor folder) and inspect the
+  generated `docs/index/md` file.
+
 ## Metadata
 
 Check the Wiki for the metadata creation guide:

packages/http/ast.json

@@ -38,7 +38,7 @@
             "description": "Query, Headers and Authentication parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -101,7 +101,7 @@
             "description": "Body, Query, Headers and Authentication parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -164,7 +164,7 @@
             "description": "Body, Query, Headers and Auth parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -227,7 +227,7 @@
             "description": "Body, Query, Headers and Auth parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -290,7 +290,7 @@
             "description": "Body, Query, Headers and Auth parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },

packages/http/src/Adaptor.js

@@ -10,11 +10,12 @@ import { request as sendRequest } from './Utils';
 /**
  * Options provided to the HTTP request
  * @typedef {Object} RequestOptions
- * @property {object|string} body - body data to append to the request
- * @property {object} errors - Map of errorCodes -> error messages, ie, `{ 404: 'Resource not found;' }`. Use a falsy message value to suppress errors for thiscode.
- * @property {object} query - an object of query parameters. Will be encoded into the URL.
- * @property {object} headers - an object of headers to append to the request
- * @property {string} parseAs - parse the response body as json, text or stream. By default will use the response headers.
+ * @property {object|string} body - body data to append to the request. JSON will be converted to a string (but a content-type header will not be attached to the request).
+ * @property {object} errors - Map of errorCodes -> error messages, ie, `{ 404: 'Resource not found;' }`. Pass `false` to suppress errors for this code.
+ * @property {object} form - Pass a JSON object to be serialised into a multipart HTML form (as FormData) in the body.
+ * @property {object} query - An object of query parameters to be encoded into the URL.
+ * @property {object} headers - An object of headers to append to the request.
+ * @property {string} parseAs - Parse the response body as json, text or stream. By default will use the response headers.
  * @property {number} timeout - Request timeout in ms. Default: 300 seconds.
  * @property {object} tls - TLS/SSL authentication options. See https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
  */
@@ -46,10 +47,14 @@ export function execute(...operations) {
  * Make a HTTP request
  * @public
  * @example
- * get('/myEndpoint', {
- *   query: {foo: 'bar', a: 1},
- *   headers: {'content-type': 'application/json'},
- * })
+ * request(
+ *   'GET',
+ *   '/myEndpoint',
+ *    {
+ *      query: {foo: 'bar', a: 1},
+ *      headers: {'content-type': 'application/json'},
+ *    }
+ * )
  * @function
  * @param {string} method - The HTTP method to use
  * @param {string} path - Path to resource

tools/build/src/commands/docs.ts

@@ -1,6 +1,7 @@
 import jsdoc2md from 'jsdoc-to-markdown';
 import fs from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import path from 'node:path';
 import { writeFile, mkdir } from 'node:fs/promises';
 import resolvePath from '../util/resolve-path';
 
@@ -33,9 +34,17 @@ export default async (lang: string) => {
     return 0;
   });
 
+  const helper = path.resolve('../../tools/build/src/util/hbs-helpers.js');
   const renderOpts = {
     template: `${template}`,
+    helper,
     data: templateData,
+    partial: [
+      // TODO we should be able to automate this
+      path.resolve('../../tools/build/src/partials/body.hbs'),
+      path.resolve('../../tools/build/src/partials/description.hbs'),
+      path.resolve('../../tools/build/src/partials/link.hbs'),
+    ],
     separators: true,
     'name-format': false,
     'no-gfm': false,

tools/build/src/partials/body.hbs

@@ -0,0 +1,29 @@
+{{>deprecated~}}
+{{>description~}}
+{{!-- {{>scope~}} --}}
+{{>summary~}}
+{{>augments~}}
+{{>implements~}}
+{{>mixes~}}
+{{>default~}}
+{{>chainable~}}
+{{>overrides~}}
+{{>returns~}}
+{{>category~}}
+{{>throws~}}
+{{>fires~}}
+{{>this~}}
+{{!-- {{>access~}} --}}
+{{>readOnly~}}
+{{>requires~}}
+{{>customTags~}}
+{{>see~}}
+{{>since~}}
+{{>version~}}
+{{>authors~}}
+{{>license~}}
+{{>copyright~}}
+{{>todo~}}
+{{>params~}}
+{{>properties~}}
+{{>examples~}}

tools/build/src/partials/description.hbs

@@ -0,0 +1,5 @@
+{{#if description}}
+
+{{{inlineLinks description}}}
+
+{{/if}}

tools/build/src/partials/link.hbs

@@ -0,0 +1,26 @@
+{{! usage: link to="namepath" html=true/false caption="optional caption"~}}
+
+{{~#if html~}}
+<code>
+
+{{~#link to~}}
+{{#if url~}}
+<a href="{{{url}}}">{{#if ../../caption}}{{../../../caption}}{{else}}{{name}}{{/if}}</a>
+{{~else~}}
+{{#if ../../caption}}{{../../../caption}}{{else}}{{name}}{{/if~}}
+{{/if~}}
+{{/link~}}
+
+</code>
+{{~else~}}
+
+{{#link to~}}
+{{#if url~}}
+{{! lowercase the url}}
+[<code>{{#if ../../caption}}{{escape ../../../caption}}{{else}}{{escape name}}{{/if}}</code>]({{toLowerCase url}})
+{{~else~}}
+<code>{{#if ../../caption}}{{escape ../../../caption}}{{else}}{{escape name}}{{/if~}}</code>
+{{~/if~}}
+{{/link~}}
+
+{{/if~}}

tools/build/src/util/docs-template.hbs

@@ -7,7 +7,7 @@
 {{/if~}}
 <dt>
     {{#if name}}{{#sig no-gfm=true ~}}
-<a href="#{{{anchorName}}}">
+<a href="#{{toLowerCase (anchorName)}}">
 {{~{@codeOpen}~}}
 {{#if @prefix}}{{@prefix}} {{/if~}}
 {{@accessSymbol}}{{#if (isEvent)}}"{{{name}}}"{{else}}{{{name}}}{{/if~}}
@@ -22,7 +22,7 @@
 {{/if~}}
 {{/globals~}}
 
-{{>global-index-kinds kind="typedef" title="Typedefs" ~}}
+{{!-- {{>global-index-kinds kind="typedef" title="Typedefs" ~}} --}}
 
 {{/if~}}
 {{#orphans ~}}

tools/build/src/util/hbs-helpers.js

@@ -0,0 +1,3 @@
+exports.toLowerCase = function (str) {
+  return str ? str.toLowerCase() : str;
+};