chore(docs): migrating to typedoc and upgrading mkdocs+material…

… packages (#8491) Huge lift to get the documentation site in a much better state. Upgrading `mkdoc` and related theme packages. Migrated to `typedoc` for a variety of reasons, most notably that it can provide more info of properties when rendered (such as `@deprecated` messages) Migrates `docs` dir to `pages` as template documents. We copy this over to `docs` before generating `.md` with typedoc into `docs` dir. This is all automatically handled when we run `pnpm docs:all` (if local) or `sh ./netlify-docs.sh` (if netlify) Dynamically inserts `.md` files via `{% includes <path> %}` tags to streamline maintaining parity with released state of typedoc. Adjusts CSS to allow full width of browser window to be used (better readability of docs)
electron-userland · Sep 17, 2024 · 178a3c4 · 178a3c4
1 parent 5e21509
commit 178a3c4
Show file tree

Hide file tree

Showing 136 changed files with 2,052 additions and 8,968 deletions.
diff --git a/.changeset/red-beers-press.md b/.changeset/red-beers-press.md
@@ -0,0 +1,16 @@
+---
+"app-builder-lib": patch
+"builder-util": patch
+"builder-util-runtime": patch
+"dmg-builder": patch
+"electron-builder": patch
+"electron-builder-squirrel-windows": patch
+"electron-forge-maker-appimage": patch
+"electron-forge-maker-nsis": patch
+"electron-forge-maker-nsis-web": patch
+"electron-forge-maker-snap": patch
+"electron-publish": patch
+"electron-updater": patch
+---
+
+chore: migrating to typedoc and updating/improving type+interface definitions
diff --git a/.gitignore b/.gitignore
@@ -15,14 +15,14 @@ out/
 /test/test-report.xml
 
 /packages/dmg-builder/vendor/
-/packages/electron-builder/README.md
 
 /scripts/jsdoc/out/
 /scripts/renderer/out/
 
-electron-builder-*.d.ts
+docs/
+site/
 
-/site/
+electron-builder-*.d.ts
 
 tsconfig.tsbuildinfo
 

diff --git a/Pipfile b/Pipfile
@@ -4,13 +4,13 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-mkdocs-material = "<10"
-mkdocs = "<1.7"
-markdown-include = "<0.8.1"
-pymdown-extensions = "~=10.3"
-pygments = "~=2.0"
+mkdocs = "*"
+mkdocs-include-markdown-plugin = "*"
+pymdown-extensions = "*"
+pygments = "*"
+mkdocs-material = "*"
 
 [dev-packages]
 
 [requires]
-python_version = "3"
+python_version = "^3.8"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
       <td>
          <a href="https://workflowy.com">
             <div>
-               <img src="https://workflowy.com/media/i/icon-28x28.png" alt="WorkFlowy" title="WorkFlowy" height="50" align="middle"/>
+               <img src="https://workflowy.com/media/i/icon-28x28.png" alt="WorkFlowy" title="WorkFlowy" style="height: 50px;" height="50"/>
             </div>
             Notes, Tasks, Projects.<br>All in a Single Place.
          </a>
@@ -24,7 +24,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://tidepool.org">
             <div>
-               <img src="https://www.electron.build/sponsor-logos/Tidepool_Logo_Light.svg" alt="Tidepool" title="Tidepool" height="75" align="middle"/>
+               <img src="https://www.electron.build/sponsor-logos/Tidepool_Logo_Light.svg" alt="Tidepool" title="Tidepool" style="height: 75px;" height="75" />
             </div>
             Your gateway to understanding your diabetes data
          </a>
@@ -34,7 +34,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://keygen.sh/?via=electron-builder">
             <div>
-               <img src="https://keygen.sh/images/logo-pill.png" alt="Keygen" title="Keygen" height="75" align="middle"/>
+               <img src="https://keygen.sh/images/logo-pill.png" alt="Keygen" title="Keygen" style="height: 75px;" height="75" />
             </div>
             An open, source-available software licensing and distribution API
          </a>
@@ -46,7 +46,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://www.todesktop.com/electron?utm_source=electron-builder">
             <div>
-               <img src="https://www.todesktop.com/new-logo/todesktop-logo.png" alt="ToDesktop" title="ToDesktop" height="75" align="middle"/>
+               <img src="https://www.todesktop.com/new-logo/todesktop-logo.png" alt="ToDesktop" title="ToDesktop" style="height: 75px;" height="75" />
             </div>
             ToDesktop: An all-in-one platform for building and releasing Electron apps
          </a>
@@ -56,7 +56,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://www.dashcam.io/?ref=electron_builder">
             <div>
-               <img src="https://user-images.githubusercontent.com/318295/226675216-ab6aad0c-526c-4a45-a0a8-3906ac614b8b.png" alt="Dashcam" title="Dashcam" height="75" align="middle"/>
+               <img src="https://user-images.githubusercontent.com/318295/226675216-ab6aad0c-526c-4a45-a0a8-3906ac614b8b.png" alt="Dashcam" title="Dashcam" style="height: 75px;" height="75" />
             </div>
             Dashcam: Capture the steps to reproduce any bug with video crash reports for Electron.
          </a>
@@ -78,24 +78,24 @@ See the full documentation on [electron.build](https://www.electron.build).
 * [Auto Update](https://www.electron.build/auto-update) ready application packaging.
 * Numerous target formats:
     * All platforms: `7z`, `zip`, `tar.xz`, `tar.7z`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir` (unpacked directory).
-    * [macOS](https://www.electron.build/configuration/mac): `dmg`, `pkg`, `mas`.
-    * [Linux](https://www.electron.build/configuration/linux): [AppImage](http://appimage.org), [snap](http://snapcraft.io), debian package (`deb`), `rpm`, `freebsd`, `pacman`, `p5p`, `apk`.
-    * [Windows](https://www.electron.build/configuration/win): `nsis` (Installer), `nsis-web` (Web installer), `portable` (portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows.
-* [Publishing artifacts](https://www.electron.build/configuration/publish) to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray.
+    * [macOS](https://www.electron.build/mac): `dmg`, `pkg`, `mas`.
+    * [Linux](https://www.electron.build/linux): [AppImage](http://appimage.org), [snap](http://snapcraft.io), debian package (`deb`), `rpm`, `freebsd`, `pacman`, `p5p`, `apk`.
+    * [Windows](https://www.electron.build/win): `nsis` (Installer), `nsis-web` (Web installer), `portable` (portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows.
+* [Publishing artifacts](https://www.electron.build/publish) to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray.
 * Advanced building:
     * Pack in a distributable format [already packaged app](https://www.electron.build/#pack-only-in-a-distributable-format).
     * Separate [build steps](https://github.com/electron-userland/electron-builder/issues/1102#issuecomment-271845854).
     * Build and publish in parallel, using hard links on CI server to reduce IO and disk space usage.
     * [electron-compile](https://github.com/electron/electron-compile) support (compile for release-time on the fly on build).
 * [Docker](https://www.electron.build/multi-platform-build#docker) images to build Electron app for Linux or Windows on any platform.
-* [Proton Native](https://www.electron.build/configuration/configuration/#proton-native) support.
+* [Proton Native](https://www.electron.build/configuration/#proton-native) support.
 * Downloads all required tools files on demand automatically (e.g. to code sign windows application, to make AppX), no need to setup.
 
-| Question | Answer |
-|----------|-------|
-| “I want to configure electron-builder” | [See options](https://electron.build/configuration/configuration) |
-| “I found a bug or I have a question” | [Open an issue](https://github.com/electron-userland/electron-builder/issues/new) |
-| “I want to support development” | [Donate](https://www.electron.build/donate) |
+| Question                               | Answer                                                                            |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| “I want to configure electron-builder” | [See options](https://electron.build/configuration)                 |
+| “I found a bug or I have a question”   | [Open an issue](https://github.com/electron-userland/electron-builder/issues/new) |
+| “I want to support development”        | [Donate](https://www.electron.build/donate)                                       |
 
 ## Installation
 [Yarn](http://yarnpkg.com/) is [strongly](https://github.com/electron-userland/electron-builder/issues/1147#issuecomment-276284477) recommended instead of npm.
@@ -129,9 +129,9 @@ will declare to use node-modules instead of PnP.
 
 [electron-webpack-quick-start](https://github.com/electron-userland/electron-webpack-quick-start) is a recommended way to create a new Electron application. See [Boilerplates](https://www.electron.build/#boilerplates).
 
-1. Specify the standard fields in the application `package.json` — [name](https://electron.build/configuration/configuration#Metadata-name), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).
+1. Specify the standard fields in the application `package.json` — [name](https://electron.build./configuration.md#Metadata-name), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).
 
-2. Specify the [build](https://electron.build/configuration/configuration#build) configuration in the `package.json` as follows:
+2. Specify the [build](https://electron.build./configuration.md#build) configuration in the `package.json` as follows:
     ```json
     "build": {
       "appId": "your.id",
@@ -140,7 +140,7 @@ will declare to use node-modules instead of PnP.
       }
     }
     ```
-   See [all options](https://www.electron.build/configuration/configuration). Option [files](https://www.electron.build/configuration/contents#files) to indicate which files should be packed in the final application, including the entry file, maybe required.
+   See [all options](https://www.electron.build/configuration). Option [files](https://www.electron.build/contents#files) to indicate which files should be packed in the final application, including the entry file, maybe required.
    You can also use separate configuration files, such as `js`, `ts`, `yml`, and `json`/`json5`. See [read-config-file](https://www.npmjs.com/package/read-config-file) for supported extensions. [JS Example for programmatic API](https://www.electron.build/api/programmatic-usage)
 
 3. Add [icons](https://www.electron.build/icons).
@@ -156,12 +156,70 @@ will declare to use node-modules instead of PnP.
 
     To ensure your native dependencies are always matched electron version, simply add script `"postinstall": "electron-builder install-app-deps"` to your `package.json`.
 
-5. If you have native addons of your own that are part of the application (not as a dependency), set [nodeGypRebuild](https://www.electron.build/configuration/configuration#Configuration-nodeGypRebuild) to `true`.
+5. If you have native addons of your own that are part of the application (not as a dependency), set [nodeGypRebuild](https://www.electron.build./configuration.md#Configuration-nodeGypRebuild) to `true`.
 
-Please note that everything is packaged into an asar archive [by default](https://electron.build/configuration/configuration#Configuration-asar).
+Please note that everything is packaged into an asar archive [by default](https://electron.build./configuration.md#Configuration-asar).
 
 For an app that will be shipped to production, you should sign your application. See [Where to buy code signing certificates](https://www.electron.build/code-signing#where-to-buy-code-signing-certificate).
 
+## Programmatic Usage
+See `node_modules/electron-builder/out/index.d.ts`. Typings for TypeScript are provided and also can be found [here](/api/electron-builder.md).
+
+Code snippit provided below is also shown "in action" [here](/api/programmatic-usage.md) as well.
+```js
+"use strict"
+
+const builder = require("electron-builder")
+const Platform = builder.Platform
+
+// Promise is returned
+builder.build({
+  targets: Platform.MAC.createTarget(),
+  config: {
+   "//": "build options, see https://goo.gl/QQXmcV"
+  }
+})
+  .then(() => {
+    // handle result
+  })
+  .catch((error) => {
+    // handle error
+  })
+```
+
+## Boilerplates
+
+* [electron-webpack-quick-start](https://github.com/electron-userland/electron-webpack-quick-start) — A bare minimum project structure to get started developing with [electron-webpack](https://github.com/electron-userland/electron-webpack). Recommended.
+* [electron-react-boilerplate](https://github.com/chentsulin/electron-react-boilerplate) A boilerplate for scalable cross-platform desktop apps.
+* [electron-react-redux-boilerplate](https://github.com/jschr/electron-react-redux-boilerplate) A minimal boilerplate to get started with Electron, React and Redux.
+* [electron-boilerplate](https://github.com/szwacz/electron-boilerplate) A minimalistic yet comprehensive boilerplate application.
+* [Vue CLI 3 plugin for Electron](https://nklayman.github.io/vue-cli-plugin-electron-builder) A Vue CLI 3 plugin for Electron with no required configuration.
+* [electron-vue-vite](https://github.com/caoxiemeihao/electron-vue-vite) A real simple Electron + Vue3 + Vite5 boilerplate.
+* [vite-electron-builder](https://github.com/cawa-93/vite-electron-builder) Secure boilerplate for Electron app based on Vite. TypeScript + Vue/React/Angular/Svelte/Vanilla
+
+## Debug
+
+Set the `DEBUG` environment variable to debug what electron-builder is doing:
+```bash
+DEBUG=electron-builder
+```
+
+`FPM_DEBUG` env to add more details about building linux targets (except snap and appimage).
+
+`DEBUG_DMG=true` env var to add more debugging/verbosity from `hdiutil` (macOS).
+
+!!! tip "cmd"
+    On [Windows](https://github.com/visionmedia/debug#windows-command-prompt-notes) the environment variable is set using the set command.
+    ```bash
+    set DEBUG=electron-builder
+    ```
+
+!!! tip "PowerShell"
+    PowerShell uses different syntax to set environment variables.
+    ```bash
+    $env:DEBUG=electron-builder
+    ```
+
 ## Donate
 
 We do this open source work in our free time. If you'd like us to invest more time on it, please [donate](https://www.electron.build/donate).