chore(docs): move docs to README.md (#1013)

Refs: #980

## Description of Changes

Move useful usage docs from JSDoc code comments to `README.md`.

README.md

@@ -15,93 +15,297 @@ For version 3, please go to the [corresponding branch](https://github.com/nwutil
 - Downloading from mirrors
 - Node Native Addon support
 
-## Installation
+## Table of Contents
 
-With npm:
+- [Installation](https://github.com/nwutils/nw-builder#install)
+- [Usage](https://github.com/nwutils/nw-builder#usage)
+- [Concepts](https://github.com/nwutils/nw-builder#concepts)
+- [API Reference](https://github.com/nwutils/nw-builder#api-reference)
+- [Guides](https://github.com/nwutils/nw-builder#guides)
+- [Contributing](https://github.com/nwutils/nw-builder#contributing)
+- [Roadmap](https://github.com/nwutils/nw-builder#roadmap)
+- [FAQ](https://github.com/nwutils/nw-builder#faq)
+- [License](https://github.com/nwutils/nw-builder#license)
+
+## Install
+
+Every NW.js release includes a modified Node.js binary at a specific version. It is recommended to [install](https://nodejs.org/en/download/package-manager) exactly that version on the host system. Not doing so may download ABI incompatible Node modules. Consult the NW.js [versions manifest](https://nwjs.io/versions) for what Node.js version to install. It is recommended to use a Node version manager (such as [volta](https://volta.sh), n, nvm, or nvm-windows) to be able to easily install and switch between Node versions.
+
+For example, NW.js v0.83.0 comes with Node.js v21.1.0.
 
 ```shell
-npm i -D nw-builder
+$: node --version
+v21.1.0
 ```
 
-With yarn:
+## Usage
 
-```shell
-yarn add -D nw-builder
+This package can be used via a command line interface, be imported as a JavaScript module, or configured via the Node manifest as a JSON object.
+
+ESM import:
+
+```javascript
+import nwbuild from "nw-builder";
 ```
 
-With pnpm:
+CJS import:
 
-```shell
-pnpm add -D nw-builder
+```javascript
+let nwbuild;
+import("nwbuild")
+  .then((object) => {
+    nwbuild = obj;
+  })
+  .catch((error) => {
+    console.error(error);
+  });
 ```
 
-## Usage
+Node manifest usage:
 
-You can use this package via CLI or JavaScript module. To customise your configuration options, please consult the [documentation](https://nwutils.io/nw-builder/).
+```json
+{
+    "nwbuild": {
+        // user specified options
+    }
+}
+```
 
-### CLI
+> From here on we will show `nw-builder` functionality by using the JavaScript module. Please note that the same method applies when using a command line or Node manifest.
 
-Download NW.js binary
+## Concepts
 
-```shell
-nwbuild --mode=get
+`nw-builder` can get, run and build NW.js applications. We refer to them as get, run and build modes.
+
+### Get Mode
+
+By default you get the normal build of the latest NW.js release for your specific platform and arch. For more information, please refer to the API reference.
+
+```javascript
+nwbuild({
+  mode: "get"
+});
 ```
 
-Run NW.js application
+Get the community built FFmeg which contains proprietary codecs. This options is disabled by default. Please read the [license's constraints](https://nwjs.readthedocs.io/en/latest/For%20Developers/Enable%20Proprietary%20Codecs/#get-ffmpeg-binaries-from-the-community) before enabling this option.
 
-```shell
-nwbuild --mode=run
+```javascript
+nwbuild({
+  mode: "get",
+  ffmpeg: true
+});
 ```
 
-Build NW.js application
+Get Node headers if you have to rebuild Node addons.
 
-```shell
-nwbuild --mode=get
+```javascript
+nwbuild({
+  mode: "get",
+  nativeAddon: "gyp"
+});
 ```
 
-### Module
+### Run Mode
 
-ESM import
+```javascript
+nwbuild({
+  mode: "run",
+  srcDir: "./app",
+  glob: false,
+});
+```
+
+### Build Mode
+
+Build with defaults:
 
 ```javascript
-import nwbuild from "nw-builder";
+nwbuild({
+  mode: "build",
+});
 ```
 
-CJS import
+Managed Manifest
+
+You can let `nw-builder` manage your node modules. The `managedManifest` options accepts a `boolean`, `string` or `object` type. It will then remove `devDependencies`, autodetect and download `dependencies` via the relevant `packageManager`. If none is specified, it uses `npm` as default.
+
+Setting it to `true` will parse the first Node manifest it encounters as the NW manifest.
 
 ```javascript
-import nwbuild from "nw-builder";
+nwbuild({
+  mode: "build",
+  managedManifest: true,
+});
+```
+
+Setting it to a `string` implies that you are passing the file path to the NW manifest.
+
+```javascript
+nwbuild({
+  mode: "build",
+  managedManifest: "./nw.js",
+});
+```
 
-let nwbuild = undefined;
+Setting it to a `object` implies you are directly passing the NW manifest as a JavaScript object.
 
-nwbuild = await import("nw-builder").default;
+```javascript
+nwbuild({
+  mode: "build",
+  managedManifest: {
+    name: "nwdemo",
+    main: "index.html"
+  },
+});
 ```
 
-Download NW.js binary
+Rebuild Node addons
+
+Currently this feature is quite limited. It only builds node addons which have a `binding.gyp` file in the `srcDir`. There are plans to support nan, cmake, ffi and gn and auto rebuild native addons which are installed as node modules.
+
+```javascript
+nwbuild({
+  mode: "build",
+  nodeAddon: "gyp",
+});
+```
+
+We recommend rebuilding Node addons for NW.js via `node-gyp` if you are using NW.js v0.83.0 or above.
+
+```shell
+node-gyp rebuild --target=21.1.0 --nodedir=/path/to/nw/node/headers
+```
+
+NW.js's Node version should match the Node version on the host machine due to [ABI differences in V8](https://github.com/nwjs/nw.js/issues/5025).
+
+## API Reference
+
+Options
+
+| Name | Type    | Default   | Description |
+| ---- | ------- | --------- | ----------- |
+| mode | `"get" \| "run" \| "build"` | `"build"` | Choose between get, run or build mode |
+| version | `string \| "latest" \| "stable"` | `"latest"` | Runtime version |
+| flavor | `"normal" \| "sdk"` | `"normal"` | Runtime flavor |
+| platform | `"linux" \| "osx" \| "win"` | | Host platform |
+| arch | `"ia32" \| "x64" \| "arm64"` | | Host architecture |
+| downloadUrl | `"https://dl.nwjs.io" \| "https://npm.taobao.org/mirrors/nwjs" \| https://npmmirror.com/mirrors/nwjs \| "https://github.com/corwin-of-amber/nw.js/releases/"` | `"https://dl.nwjs.io"` | Download server |
+| manifestUrl | `"https://nwjs.io/versions" \| "https://raw.githubusercontent.com/nwutils/nw-builder/main/src/util/osx.arm.versions.json"` | `"https://nwjs.io/versions"` | Versions manifest |
+| cacheDir | `string` | `"./cache"` | Directory to cache NW binaries |
+| srcDir | `string` | `"./"` | File paths to application code |
+| outDir | `string` | `"./out"` | Directory to store build artifacts |
+| managedManifest | `boolean \| string \| object` | `false` | Managed manifest |
+| nodeAddon | `false \| "gyp"` | `false` | Rebuild Node native addons |
+| cache | `boolean` | `true`| If true the existing cache is used. Otherwise it removes and redownloads it. |
+| ffmpeg | `boolean` | `false`| If true the chromium ffmpeg is replaced by community version with proprietary codecs. |
+| glob | `boolean` | `true`| If true file globbing is enabled when parsing `srcDir`. |
+| logLevel | `"error" \| "warn" \| "info" \| "debug"` | `"info"`| Specify level of logging. |
+| zip | `boolean \| "zip" \| "tar" \| "tgz"` | `false`| If true, "zip", "tar" or "tgz" the `outDir` directory is compressed. |
+
+
+## Guides
+
+### Get unofficial MacOS builds
+
+If you're running older Apple machines, you can download the unofficial builds.
+
+> Note: You will have to manually remove quarantine flag.
+
+```shell
+sudo xattr -r -d com.apple.quarantine /path/to/nwjs.app
+```
 
 ```javascript
 nwbuild({
   mode: "get",
+  platform: "osx",
+  arch: "arm64",
+  downloadUrl: "https://github.com/corwin-of-amber/nw.js/releases/download",
+  manifestUrl: "https://raw.githubusercontent.com/nwutils/nw-builder/main/src/util/osx.arm.versions.json",
 });
 ```
 
-Run NW.js application
+> Note: Community FFmpeg binaries may not be available for unofficial builds. You will have to rebuild them yourself.
+
+### Get binaries via mirrors
+
+China mirror:
 
 ```javascript
 nwbuild({
-  mode: "run",
+  mode: "get",
+  downloadUrl: "https://npm.taobao.org/mirrors/nwjs",
+});
+```
+
+Singapore mirror:
+
+```javascript
+nwbuild({
+  mode: "get",
+  downloadUrl: "https://cnpmjs.org/mirrors/nwjs/",
 });
 ```
 
-Build NW.js application
+### Let `nw-builder` manage your native addons
+
+> Note: this behaviour is buggy and quite limited. This guide is to show what will be possible in the coming minor releases.
 
 ```javascript
 nwbuild({
   mode: "build",
+  managedManifest: true,
+  nativeAddon: "gyp",
 });
 ```
 
-## Alternatives
+## Contributing
+
+### External contributor
+
+- We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) style of commit messages.
+- Pull requests are squashed and merged onto the `main` branch.
+- Lint your code before commiting your change.
+- Add tests whenever possible.
+
+### Maintainer guidelines
+
+## Roadmap
+
+### Bugs
+
+- https://github.com/nwutils/nw-builder/issues/1000
+- https://github.com/nwutils/nw-builder/issues/1002
+- Add back error, info and debug logs
+
+### Features
+
+- feat(get): support canary releases
+- feat(bld): rename MacOS Helper apps
+- feat(pkg): add `AppImage` installer
+- feat(pkg): add `NSIS` installer
+- feat(pkg): add `DMG` installer
+- feat(get): add Linux ARM unofficial support
+- feat(bld): add source code protection
+- feat(pkg): add code signing
+
+### Chores
+
+- chore(cicd): use `google-github-actions/release-please-action` to automate publishing to npm, updating changelog and creating releases
+- chore(test): add test cases for current features
+- chore(yargs): migrate to `commander`
+- chore(node:test): migrate to `vitest`
+- chore(unzipper): migrate to `yauzl-promise`
+- chore(util): factor out nw file paths finder
+- chore(get): factor out https downloader
+- chore(get): factor out nwjs downloader
+- chore(get): factor out ffmpeg downloader
+- chore(get): factor out node headers downloader
+- chore(get): verify sha checksum for downloads
+- chore(bld): move `.desktop` entry file logic to `create-desktop-shortcuts` package
+
+## FAQ
+
+## License
 
-- [nw-builder-platforms](https://github.com/naviapps/nw-builder-platforms) - Fork of this repo with platform specific build options
-- [nwjs-builder-phoenix](https://github.com/evshiron/nwjs-builder-phoenix) - Previously the most used build tool, however it is no longer maintained
+MIT License.