chore(docs): more improvements and clarity - extracting more docs fro…

…m documentation site directly into typedocs (#8495)

- Removes inherited members being printed out under each included
template
- Fixing Table of Contents by removing duplicate `<h1>` tags
- Fixing up hooks documentation and adding directly to typedoc comments

.changeset/chilly-deers-cry.md

@@ -0,0 +1,5 @@
+---
+"app-builder-lib": patch
+---
+
+chore(docs): updating typedocs by extracting docs from documentation .md files

mkdocs-dockerfile

@@ -1,4 +1,5 @@
 FROM squidfunk/mkdocs-material
 RUN pip install mkdocs-include-markdown-plugin
 RUN pip install pymdown-extensions
-RUN pip install pygments
+RUN pip install pygments
+RUN pip install markdown-include

mkdocs.yml

@@ -15,6 +15,7 @@ theme:
     - header.autohide
     - navigation.expand
     - navigation.sections
+    # - navigation.prune
     # - search.highlight
     # - search.share
     # - search.suggest
@@ -62,35 +63,25 @@ markdown_extensions:
   - pymdownx.superfences
   - toc:
       permalink: true
+  - markdown_include.include:
+      base_path      : './docs/'
+      encoding       : 'utf-8'
 
 plugins:
   - search
-  # - minify:
-  #     minify_html: true
-  - include-markdown:
-      # encoding: ascii
-      preserve_includer_indent: true
-      # dedent: true
-      trailing_newlines: true
-      # inheritHeadingDepth: true
-      # comments: true
-      rewrite_relative_urls: true
-      # heading_offset: 0
-      # start: <!-- do not edit. start of generated block -->
-      # end: <!-- end of generated block -->
-      # opening_tag: "{!"
-      # closing_tag: "!}"
-      # recursive: true
 
 nav:
   - Introduction: README.md
   - Command Line Interface (CLI): cli.md
-  - Programmatic API:
-      - API: api/electron-builder.md
-      - Example: api/programmatic-usage.md
-      - Modules: modules.md
   - Donate: donate.md
 
+  - Programmatic API:
+      - Example: programmatic-usage.md
+      - Main Modules:
+        - electron-builder: electron-builder/globals.md
+        - app-builder-lib: app-builder-lib/globals.md
+        - electron-updater: electron-updater/globals.md
+
   - Configuration:
       - Common Configuration: configuration.md
 
@@ -120,7 +111,7 @@ nav:
       - Publish: publish.md
 
   - Guides:
-      - Hooks: hooks.md
+      - Build Hooks: hooks.md
       - Icons: icons.md
       - Auto Update: auto-update.md
       - Code Signing: code-signing.md

packages/app-builder-lib/scheme.json

@@ -6610,7 +6610,7 @@
           ]
         }
       ],
-      "description": "The function (or path to file or module id) to be [run after all artifacts are build](#afterAllArtifactBuild)."
+      "description": "The function (or path to file or module id) to be run after all artifacts are built.\n\n```typescript\n(buildResult: BuildResult): Promise<Array<string>> | Array<string>\n```\n\nConfiguration in the same way as `afterPack` (see above).\n\n!!! example \"myAfterAllArtifactBuild.js\"\n```js\nexports.default = function () {\n // you can return additional files to publish\n return [\"/path/to/additional/result/file\"]\n}\n```"
     },
     "afterExtract": {
       "anyOf": [
@@ -6800,7 +6800,7 @@
           ]
         }
       ],
-      "description": "The function (or path to file or module id) to be [run before pack](#beforepack)"
+      "description": "The function (or path to file or module id) to be run before pack.\n\n```typescript\n(context: BeforePackContext): Promise<any> | any\n```\n\n!!! example \"As function\"\n\n ```js\n beforePack: async (context) => {\n   // your code\n }\n ```\n\nBecause in a configuration file you cannot use JavaScript, can be specified as a path to file or module id. Function must be exported as default export.\n\n```json\n\"build\": {\n\"beforePack\": \"./myBeforePackHook.js\"\n}\n```\n\nFile `myBeforePackHook.js` in the project root directory:\n\n!!! example \"myBeforePackHook.js\"\n ```js\n exports.default = async function(context) {\n   // your custom code\n }\n ```"
     },
     "buildDependenciesFromSource": {
       "default": false,

packages/app-builder-lib/src/configuration.ts

@@ -21,7 +21,7 @@ import { NsisOptions, NsisWebOptions, PortableOptions } from "./targets/nsis/nsi
 /**
  * Configuration Options
  */
-export interface Configuration extends PlatformSpecificBuildOptions {
+export interface Configuration extends PlatformSpecificBuildOptions, Hooks {
   /**
    * The application id. Used as [CFBundleIdentifier](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102070) for MacOS and as
    * [Application User Model ID](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx) for Windows (NSIS target only, Squirrel.Windows not supported). It is strongly recommended that an explicit ID is set.
@@ -216,7 +216,80 @@ export interface Configuration extends PlatformSpecificBuildOptions {
   readonly framework?: string | null
 
   /**
-   * The function (or path to file or module id) to be [run before pack](#beforepack)
+   * Whether to include PDB files.
+   * @default false
+   */
+  readonly includePdb?: boolean
+
+  /**
+   * Whether to remove `scripts` field from `package.json` files.
+   *
+   * @default true
+   */
+  readonly removePackageScripts?: boolean
+
+  /**
+   * Whether to remove `keywords` field from `package.json` files.
+   *
+   * @default true
+   */
+  readonly removePackageKeywords?: boolean
+
+  /**
+   * Whether to disable sanity check asar package (useful for custom electron forks that implement their own encrypted integrity validation)
+   * @default false
+   */
+  readonly disableSanityCheckAsar?: boolean
+}
+
+export type CustomElectronDistributable = (options: PrepareApplicationStageDirectoryOptions) => string
+
+export type Hook<T, V> = (contextOrPath: T) => Promise<V> | V
+
+export interface PackContext {
+  readonly outDir: string
+  readonly appOutDir: string
+  readonly packager: PlatformPackager<any>
+  readonly electronPlatformName: string
+  readonly arch: Arch
+  readonly targets: Array<Target>
+}
+export type AfterPackContext = PackContext
+export type BeforePackContext = PackContext
+export type AfterExtractContext = PackContext
+
+export interface Hooks {
+  /**
+The function (or path to file or module id) to be run before pack.
+
+```typescript
+(context: BeforePackContext): Promise<any> | any
+```
+
+!!! example "As function"
+
+    ```js
+    beforePack: async (context) => {
+      // your code
+    }
+    ```
+
+Because in a configuration file you cannot use JavaScript, can be specified as a path to file or module id. Function must be exported as default export.
+
+```json
+"build": {
+  "beforePack": "./myBeforePackHook.js"
+}
+```
+
+File `myBeforePackHook.js` in the project root directory:
+
+!!! example "myBeforePackHook.js"
+    ```js
+    exports.default = async function(context) {
+      // your custom code
+    }
+    ```
    */
   readonly beforePack?: Hook<BeforePackContext, any> | string | null
 
@@ -244,7 +317,21 @@ export interface Configuration extends PlatformSpecificBuildOptions {
    */
   readonly artifactBuildCompleted?: Hook<ArtifactCreated, any> | string | null
   /**
-   * The function (or path to file or module id) to be [run after all artifacts are build](#afterAllArtifactBuild).
+   * The function (or path to file or module id) to be run after all artifacts are built.
+
+```typescript
+(buildResult: BuildResult): Promise<Array<string>> | Array<string>
+```
+
+Configuration in the same way as `afterPack` (see above).
+
+!!! example "myAfterAllArtifactBuild.js"
+    ```js
+    exports.default = function () {
+      // you can return additional files to publish
+      return ["/path/to/additional/result/file"]
+    }
+    ```
    */
   readonly afterAllArtifactBuild?: Hook<BuildResult, Array<string>> | string | null
   /**
@@ -265,46 +352,8 @@ export interface Configuration extends PlatformSpecificBuildOptions {
    * If provided and `node_modules` are missing, it will not invoke production dependencies check.
    */
   readonly beforeBuild?: Hook<BeforeBuildContext, boolean | void> | string | null
-
-  /**
-   * Whether to include PDB files.
-   * @default false
-   */
-  readonly includePdb?: boolean
-
-  /**
-   * Whether to remove `scripts` field from `package.json` files.
-   *
-   * @default true
-   */
-  readonly removePackageScripts?: boolean
-
-  /**
-   * Whether to remove `keywords` field from `package.json` files.
-   *
-   * @default true
-   */
-  readonly removePackageKeywords?: boolean
-
-  /**
-   * Whether to disable sanity check asar package (useful for custom electron forks that implement their own encrypted integrity validation)
-   * @default false
-   */
-  readonly disableSanityCheckAsar?: boolean
 }
 
-interface PackContext {
-  readonly outDir: string
-  readonly appOutDir: string
-  readonly packager: PlatformPackager<any>
-  readonly electronPlatformName: string
-  readonly arch: Arch
-  readonly targets: Array<Target>
-}
-export type AfterPackContext = PackContext
-export type BeforePackContext = PackContext
-export type AfterExtractContext = PackContext
-
 export interface MetadataDirectories {
   /**
    * The path to build resources.
@@ -325,7 +374,3 @@ export interface MetadataDirectories {
    */
   readonly app?: string | null
 }
-
-export type CustomElectronDistributable = (options: PrepareApplicationStageDirectoryOptions) => string
-
-export type Hook<T, V> = (contextOrPath: T) => Promise<V> | V

packages/app-builder-lib/src/index.ts

@@ -21,7 +21,17 @@ export {
   CompressionLevel,
 } from "./core"
 export { getArchSuffix, Arch, archFromString } from "builder-util"
-export { Configuration, AfterPackContext, MetadataDirectories, BeforePackContext, AfterExtractContext, CustomElectronDistributable, Hook } from "./configuration"
+export {
+  Configuration,
+  AfterPackContext,
+  MetadataDirectories,
+  BeforePackContext,
+  AfterExtractContext,
+  CustomElectronDistributable,
+  Hooks,
+  Hook,
+  PackContext,
+} from "./configuration"
 export { ElectronBrandingOptions, ElectronDownloadOptions, ElectronPlatformName } from "./electron/ElectronFramework"
 export { PlatformSpecificBuildOptions, AsarOptions, FileSet, Protocol, ReleaseInfo, FilesBuildOptions } from "./options/PlatformSpecificBuildOptions"
 export { FileAssociation } from "./options/FileAssociation"

pages/appimage.md

@@ -3,6 +3,6 @@ The top-level [appImage](configuration.md#Configuration-appImage) key contains s
 !!! info "Desktop Integration"
     Since electron-builder 21 desktop integration is not a part of produced AppImage file. [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher) is the recommended way to integrate AppImages.
 
-# Configuration
+## Configuration
 
-{% include "./app-builder-lib.Interface.AppImageOptions.md" %}
+{!./app-builder-lib.Interface.AppImageOptions.md!}

pages/appx.md

@@ -50,6 +50,6 @@ The only solution for now — using [Parallels Desktop for Mac](http://www.paral
 
 If you use self-signed certificate, you need to add it to "Trusted People". See [Install the certificate](https://stackoverflow.com/a/24372483/1910191).
 
-# Configuration
+## Configuration
 
-{% include "./app-builder-lib.Interface.AppXOptions.md" %}
+{!./app-builder-lib.Interface.AppXOptions.md!}

pages/configuration.md

@@ -21,44 +21,44 @@ electron-builder [configuration](#configuration) can be defined
 
 Most of the options accept `null` — for example, to explicitly set that DMG icon must be default volume icon from the OS and default rules must be not applied (i.e. use application icon as DMG icon), set `dmg.icon` to `null`.
 
-# Artifact File Name Template
+## Artifact File Name Template
 
 `${ext}` macro is supported in addition to [file macros](./file-patterns.md#file-macros).
 
-# Environment Variables from File
+## Environment Variables from File
 
 Env file `electron-builder.env` in the current dir ([example](https://github.com/motdotla/dotenv-expand/blob/1cc80d02e1f8aa749253a04a2061c0fecb9bdb69/tests/.env)). Supported only for CLI usage.
 
-# How to Read Docs
+## How to Read Docs
 
 * Name of optional property is normal, **required** is bold.
 * Type is specified after property name: `Array<String> | String`. Union like this means that you can specify or string (`**/*`), or array of strings (`["**/*", "!foo.js"]`).
 
-# Configuration
+### Configuration
 
-{% include "./app-builder-lib.Interface.Configuration.md" %}
+{!./app-builder-lib.Interface.Configuration.md!}
 
 ---
 
-# Overridable per Platform Options
+## Overridable per Platform Options
 
 Following options can be set also per platform (top-level keys [mac](mac.md), [linux](linux.md) and [win](win.md)) if need.
 
-# Base Configuration
+## Base Configuration
 
-{% include "./app-builder-lib.Interface.PlatformSpecificBuildOptions.md" %}
+{!./app-builder-lib.Interface.PlatformSpecificBuildOptions.md!}
 
-# Metadata
+## Metadata
 Some standard fields should be defined in the `package.json`.
 
-{% include "./app-builder-lib.Interface.Metadata.md" %}
+{!./app-builder-lib.Interface.Metadata.md!}
 
-# Proton Native
+## Proton Native
 
 To package [Proton Native](https://proton-native.js.org/) app, set `protonNodeVersion` option to `current` or specific NodeJS version that you are packaging for.
 Currently, only macOS and Linux supported.
 
-# Build Version Management
+## Build Version Management
 `CFBundleVersion` (macOS) and `FileVersion` (Windows) will be set automatically to `version.build_number` on CI server (Travis, AppVeyor, CircleCI and Bamboo supported).
 
-{% include "./hooks.md" %}
+{!./hooks.md!}

pages/contents.md

@@ -1,7 +1,7 @@
-# File Contents
+## File Contents
 
-{% include-markdown "./app-builder-lib.Interface.FilesBuildOptions.md" heading-offset=1 %}
+#{!./app-builder-lib.Interface.FilesBuildOptions.md!}
 
-# FileSet Configuration
+## FileSet Configuration
 
-{% include-markdown "./app-builder-lib.Interface.FileSet.md" heading-offset=2 %}
+#{!./app-builder-lib.Interface.FileSet.md!}

pages/dmg.md

@@ -18,6 +18,6 @@ The contain file should have the following format:
 }
 ```
 
-# Configuration
+## Configuration
 
-{% include "./app-builder-lib.Interface.DmgOptions.md" %}
+{!./app-builder-lib.Interface.DmgOptions.md!}