Automatically generate documentation and upload it

Generate HTML documentation and upload it to https://boxine.github.io/pintf/ .
Currently, the content of the documentation is still sparse.

Only export functions with JSDoc comments, because without `--excludeNotDocument`, [tsdoc will export _everything_](TypeStrong/typedoc#639), including stuff like `const assert = require('assert');`.

Author: phihag

.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: Generate documentation
+on:
+  push:
+    branches:    
+      - master
+      - upload-docs
+
+jobs:
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+
+      - name: Build documentation
+        run: |
+          npm install
+          make doc
+
+      - name: Upload to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 results.*
 screenshots
+doc/
 
 # Editor
 .vscode/

Makefile

@@ -6,6 +6,9 @@ lint:
 test:
 	@npm run test --silent
 
+doc: *.js tsconfig.json
+	./node_modules/.bin/typedoc --out doc --noEmit --excludeNotExported --excludeNotDocumented
+
 lockserver-dev:
 	node_modules/.bin/nodemon lockserver/lockserver.js
 

README.md

@@ -94,6 +94,8 @@ module.exports = {
 
 Note that while the above example tests a webpage with [puppeteer](https://github.com/GoogleChrome/puppeteer) and uses pintf's has native support for HTTP requests (in `net_utils`) and email sending (in `email`), tests can be anything – they just have to fail the promise if the test fails.
 
+Have a look in the [API documentation](https://boxine.github.io/pintf/index.html) for various helper functions.
+
 ## Configuration
 
 pintf is designed to be run against different configurations, e.g. local/dev/stage/prod. Create JSON files in the `config` subdirectory for each environment. You can also add a programatic configuration by passing a function `defaultConfig` to `pintf.main`; see [pintf's own run](run) for an example. 

browser_utils.js

@@ -1,4 +1,9 @@
 'use strict';
+/**
+ * Browser functions, based upon puppeteer.
+ * These functions extend [the puppeteer API](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md).
+ * @packageDocumentation
+ */
 
 const assert = require('assert');
 const fs = require('fs');
@@ -11,10 +16,10 @@ const {assertAsyncEventually, wait, remove} = require('./utils');
 let tmp_home;
 
 /**
- * Launch a new page
- * @param {*} config 
- * @param {string[]} [chrome_args] 
- * @returns {import('puppeteer').Page}
+ * Launch a new browser, with a new page (=Tab)
+ * @param {*} config The pintf configuration
+ * @param {string[]} [chrome_args] Additional arguments for Chrome (optional)
+ * @returns {import('puppeteer').Page} The puppeteer page handle.
  */
 async function newPage(config, chrome_args=[]) {
     let puppeteer;

package-lock.json

@@ -28,6 +28,7 @@
     "nodemon": "^1.18.11",
     "puppeteer": "^2.1.1",
     "rimraf": "^3.0.2",
+    "typedoc": "^0.17.3",
     "typescript": "^3.8.3"
   },
   "peerDependencies": {

package.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "module": "CommonJS",
     "allowJs": true,
+    "alwaysStrict": true,
     "declaration": true,
     "emitDeclarationOnly": true,
   },