build: publish TypeScript API docs to GitHub Pages

Author: malept

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Publish documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - v[0-9]+.[0-9]+.[0-9]+*
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Fetch all git branches
+        run: git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/*
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      - run: npm install --engine-strict --no-lockfile
+      - run: npm run docs:build
+      - uses: docker://malept/gha-gh-pages:1.0.0
+        with:
+          docsPath: typedoc
+          showUnderscoreFiles: true
+          versionDocs: true
+        env:
+          DOCS_SSH_DEPLOY_KEY: ${{ secrets.DOCS_SSH_DEPLOY_KEY }}

.gitignore

@@ -8,6 +8,7 @@ yarn.lock
 test/fixtures/basic/main-link.js
 !test/fixtures/prune-is-module/node_modules
 test/work
+typedoc
 .DS_Store
 .nyc_output
 npm-debug.log

README.md

@@ -10,7 +10,7 @@ Package your [Electron](https://electronjs.org) app into OS-specific bundles (`.
 [Supported Platforms](#supported-platforms) |
 [Installation](#installation) |
 [Usage](#usage) |
-[API](https://github.com/electron/electron-packager/blob/master/docs/api.md) |
+[API](https://electron.github.io/electron-packager/master/) |
 [Contributing](https://github.com/electron/electron-packager/blob/master/CONTRIBUTING.md) |
 [Support](https://github.com/electron/electron-packager/blob/master/SUPPORT.md) |
 [Related Apps/Libraries](#related) |
@@ -72,7 +72,7 @@ later needs to be installed. On macOS, it is installable via [Homebrew](http://b
 
 ## Usage
 
-JavaScript API usage can be found in the [API documentation](https://github.com/electron/electron-packager/blob/master/docs/api.md).
+JavaScript API usage can be found in the [API documentation](https://electron.github.io/electron-packager/master/modules/electronpackager.html).
 
 ### From the Command Line
 
@@ -95,7 +95,7 @@ This will:
 
 For an overview of the other optional flags, run `electron-packager --help` or see
 [usage.txt](https://github.com/electron/electron-packager/blob/master/usage.txt). For
-detailed descriptions, see the [API documentation](https://github.com/electron/electron-packager/blob/master/docs/api.md).
+detailed descriptions, see the [API documentation](https://electron.github.io/electron-packager/master/modules/electronpackager.html).
 
 If `appname` is omitted, this will use the name specified by "productName" or "name" in the nearest package.json.
 

docs/_config.yml

@@ -0,0 +1 @@
+[API Documentation](https://electron.github.io/electron-packager/) has moved.

docs/api.md

@@ -14,7 +14,7 @@ and packaged modes, you'll need to [define it yourself](https://electronjs.org/d
 
 ## Why isn't my `ignore` option working?
 
-As stated in the documentation for [`ignore`](https://github.com/electron/electron-packager/blob/master/docs/api.md#ignore), it uses "[one] or more additional
+As stated in the documentation for [`ignore`](https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#ignore), it uses "[one] or more additional
 [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)
 patterns. […] Please note that [glob patterns](https://en.wikipedia.org/wiki/Glob_%28programming%29)
 will not work."
@@ -44,7 +44,7 @@ console.log(require(jsonFilename));
 
 ## How do I set an icon on Linux?
 
-The docs for [`icon`](https://github.com/electron/electron-packager/blob/master/docs/api.md#icon)
+The docs for [`icon`](https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#icon)
 already show how to set an icon on your `BrowserWindow`, but your dock/taskbar may not use that and
 instead use the `Icon` value in your `.desktop` file. The [Linux distributable creators](https://github.com/electron/electron-packager#distributable-creators)
 can help you set/distribute the appropriate icon in that case.

docs/faq.md

@@ -62,6 +62,7 @@
     "pkg-up": "^3.0.1",
     "sinon": "^9.0.0",
     "tsd": "^0.11.0",
+    "typedoc": "^0.16.10",
     "typescript": "^3.7.5"
   },
   "engines": {
@@ -71,6 +72,7 @@
     "ava": "ava test/index.js",
     "codecov": "nyc report --reporter=text-lcov > coverage.lcov && codecov",
     "coverage": "nyc npm run ava",
+    "docs:build": "node test/ci/build_docs.js",
     "lint": "npm run lint:js && npm run lint:ts",
     "lint:js": "eslint .",
     "lint:ts": "eslint --config .eslintrc.typescript.js --ext .ts .",

package.json

@@ -34,7 +34,7 @@ function errorMessageForProperty (prop) {
 
   return `Unable to determine ${propDescription}. Please specify an ${propDescription}\n\n` +
     'For more information, please see\n' +
-    `https://github.com/electron/electron-packager/blob/master/docs/api.md#${hash}\n`
+    `https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#${hash}\n`
 }
 
 function resolvePromise (id, options) {

src/infer.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict'
+
+const { Application } = require('typedoc')
+
+const config = {
+  excludeExternals: true,
+  excludePrivate: true,
+  excludeProtected: true,
+  includeDeclarations: true,
+  mode: 'file'
+}
+
+const replaceRef = /^refs\/(head|tag)s\//
+
+function gitRevisionFromGitHubRef () {
+  const githubRef = process.env.GITHUB_REF
+  if (githubRef) {
+    return githubRef.replace(replaceRef, '')
+  }
+}
+
+const gitRevision = process.argv[2] || gitRevisionFromGitHubRef()
+if (gitRevision) {
+  if (/^[0-9a-f]+$/i.test(gitRevision)) {
+    config.gitRevision = gitRevision
+  } else if (gitRevision.startsWith('v')) {
+    config.includeVersion = true
+  }
+}
+
+const app = new Application()
+app.bootstrap(config)
+
+const project = app.convert(['src/index.d.ts'])
+if (project) {
+  app.generateDocs(project, 'typedoc')
+} else {
+  console.error('Could not generate API documentation from TypeScript definition!')
+  process.exit(1)
+}

test/ci/build_docs.js

@@ -54,7 +54,7 @@ extra-resource     a file to copy into the app's resources directory
 icon               the local path to an icon file to use as the icon for the app.
                    Note: Format depends on platform.
 ignore             do not copy files into app whose filenames RegExp.match this string. See also:
-                   https://github.com/electron/electron-packager/blob/master/docs/api.md#ignore
+                   https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#ignore
                    and --no-prune. Can be specified multiple times
 no-deref-symlinks  make sure symlinks are not dereferenced within the app source
 no-junk            do not ignore system junk files from the packaged app