diff --git a/.changeset/chilly-deers-cry.md b/.changeset/chilly-deers-cry.md new file mode 100644 index 00000000000..7afa46fce62 --- /dev/null +++ b/.changeset/chilly-deers-cry.md @@ -0,0 +1,5 @@ +--- +"app-builder-lib": patch +--- + +chore(docs): updating typedocs by extracting docs from documentation .md files diff --git a/mkdocs-dockerfile b/mkdocs-dockerfile index 14f1cb95c9a..689caaf2b58 100644 --- a/mkdocs-dockerfile +++ b/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 \ No newline at end of file +RUN pip install pygments +RUN pip install markdown-include diff --git a/mkdocs.yml b/mkdocs.yml index dc8a35a3f33..476bbb19e44 100644 --- a/mkdocs.yml +++ b/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: - # end: - # 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 diff --git a/packages/app-builder-lib/scheme.json b/packages/app-builder-lib/scheme.json index 0515a2c9d9e..4524f3c3680 100644 --- a/packages/app-builder-lib/scheme.json +++ b/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\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\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, diff --git a/packages/app-builder-lib/src/configuration.ts b/packages/app-builder-lib/src/configuration.ts index f4187cd8c1e..1234549fcbf 100644 --- a/packages/app-builder-lib/src/configuration.ts +++ b/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 = (contextOrPath: T) => Promise | V + +export interface PackContext { + readonly outDir: string + readonly appOutDir: string + readonly packager: PlatformPackager + readonly electronPlatformName: string + readonly arch: Arch + readonly targets: Array +} +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 +``` + +!!! 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 | string | null @@ -244,7 +317,21 @@ export interface Configuration extends PlatformSpecificBuildOptions { */ readonly artifactBuildCompleted?: Hook | 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 +``` + +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> | 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 | 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 - readonly electronPlatformName: string - readonly arch: Arch - readonly targets: Array -} -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 = (contextOrPath: T) => Promise | V diff --git a/packages/app-builder-lib/src/index.ts b/packages/app-builder-lib/src/index.ts index 8063d53c584..8cb973f5225 100644 --- a/packages/app-builder-lib/src/index.ts +++ b/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" diff --git a/pages/api/electron-builder.md b/pages/api/electron-builder.md deleted file mode 100644 index 0291d1a5946..00000000000 --- a/pages/api/electron-builder.md +++ /dev/null @@ -1,11 +0,0 @@ -Developer API only. See [Configuration](../configuration.md) for user documentation. - -# Electron-Builder (main entry point) -{% include "../electron-builder/globals.md" %} - -# App-Builder-Lib -{% include "../app-builder-lib/globals.md" %} - -# Electron-Updater -{% include "../electron-updater/globals.md" %} - diff --git a/pages/appimage.md b/pages/appimage.md index 005fb0b20df..fd42fb1b84b 100644 --- a/pages/appimage.md +++ b/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!} diff --git a/pages/appx.md b/pages/appx.md index 832673c25de..5da9d52e8f3 100644 --- a/pages/appx.md +++ b/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" %} \ No newline at end of file +{!./app-builder-lib.Interface.AppXOptions.md!} \ No newline at end of file diff --git a/pages/configuration.md b/pages/configuration.md index 7931ccee846..8a91a781e8f 100644 --- a/pages/configuration.md +++ b/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`. 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!} diff --git a/pages/contents.md b/pages/contents.md index 2848da0631b..23eee2b797e 100644 --- a/pages/contents.md +++ b/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 %} \ No newline at end of file +#{!./app-builder-lib.Interface.FileSet.md!} \ No newline at end of file diff --git a/pages/dmg.md b/pages/dmg.md index 07af92e1179..802650ded48 100644 --- a/pages/dmg.md +++ b/pages/dmg.md @@ -18,6 +18,6 @@ The contain file should have the following format: } ``` -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.DmgOptions.md" %} \ No newline at end of file +{!./app-builder-lib.Interface.DmgOptions.md!} \ No newline at end of file diff --git a/pages/flatpak.md b/pages/flatpak.md index 6b7de3caafa..61b33a0565c 100644 --- a/pages/flatpak.md +++ b/pages/flatpak.md @@ -15,6 +15,6 @@ If the Flatpak build process fails with an error message like "flatpak failed wi !!! example "Enable Flatpak build debug logging" `env DEBUG="@malept/flatpak-bundler" electron-builder build --linux flatpak` -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.FlatpakOptions.md" %} +{!./app-builder-lib.Interface.FlatpakOptions.md!} diff --git a/pages/hooks.md b/pages/hooks.md index 244d65549b6..9ff37dc789b 100644 --- a/pages/hooks.md +++ b/pages/hooks.md @@ -3,138 +3,4 @@ !!! note "Node.js 8" All examples assumed that you use latest Node.js 8.11.x or higher. -### beforePack - -The function (or path to file or module id) to be run before pack. - -```typescript -(context: BeforePackContext): Promise | 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 - } - ``` - - -### afterPack - -The function (or path to file or module id) to be run after pack (but before pack into distributable format and sign). - -```typescript -(context: AfterPackContext): Promise | any -``` - -!!! example "As function" - - ```js - afterPack: 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": { - "afterPack": "./myAfterPackHook.js" -} -``` - - -File `myAfterPackHook.js` in the project root directory: - -!!! example "myAfterPackHook.js" - ```js - exports.default = async function(context) { - // your custom code - } - ``` - -### afterSign - -The function (or path to file or module id) to be run after pack and sign (but before pack into distributable format). - -```typescript -(context: AfterPackContext): Promise | any -``` - -Configuration in the same way as `afterPack` (see above). - -### afterAllArtifactBuild - -The function (or path to file or module id) to be run after all artifacts are built. - -```typescript -(buildResult: BuildResult): Promise> | Array -``` - -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"] - } - ``` - -### onNodeModuleFile - -The function (or path to file or module id) to be run on each node module file. - -```typescript -(file: string) => void -``` - -Configuration in the same way as `afterPack` (see above). - ---- - -### AfterPackContext - -```typescript -interface AfterPackContext { - outDir: string - appOutDir: string - packager: PlatformPackager - electronPlatformName: string - arch: Arch - targets: Array -} -``` - -### BuildResult - -```typescript -interface BuildResult { - outDir: string - artifactPaths: Array - platformToTargets: Map> - configuration: Configuration -} -``` - - - +{!./app-builder-lib.Interface.Hooks.md!} diff --git a/pages/linux.md b/pages/linux.md index 0e3f13f2b6b..b9f95381656 100644 --- a/pages/linux.md +++ b/pages/linux.md @@ -1,20 +1,20 @@ The top-level [linux](configuration.md#Configuration-linux) key contains set of options instructing electron-builder on how it should build Linux targets. These options applicable for any Linux target. -# Base Linux Configuration +## Base Linux Configuration -{% include "./app-builder-lib.Interface.LinuxConfiguration.md" %} +{!./app-builder-lib.Interface.LinuxConfiguration.md!} -# Debian Package Options +## Debian Package Options The top-level [deb](configuration.md#Configuration-deb) key contains set of options instructing electron-builder on how it should build Debian package. -{% include "./app-builder-lib.Interface.DebOptions.md" %} +{!./app-builder-lib.Interface.DebOptions.md!} All [LinuxTargetSpecificOptions](linux.md#linuxtargetspecificoptions-apk-freebsd-pacman-p5p-and-rpm-options) can be also specified in the `deb` to customize Debian package. -# `LinuxTargetSpecificOptions` APK, FreeBSD, Pacman, P5P and RPM Options +## `LinuxTargetSpecificOptions` APK, FreeBSD, Pacman, P5P and RPM Options The top-level `apk`, `freebsd`, `pacman`, `p5p` and `rpm` keys contains set of options instructing electron-builder on how it should build corresponding Linux target. -{% include "./app-builder-lib.Interface.LinuxTargetSpecificOptions.md" %} +{!./app-builder-lib.Interface.LinuxTargetSpecificOptions.md!} diff --git a/pages/mac.md b/pages/mac.md index a9be81b0614..a727c7b52e3 100644 --- a/pages/mac.md +++ b/pages/mac.md @@ -1,9 +1,9 @@ The top-level [mac](configuration.md#Configuration-mac) key contains set of options instructing electron-builder on how it should build macOS targets. These options applicable for any macOS target. -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.MacConfiguration.md" %} +{!./app-builder-lib.Interface.MacConfiguration.md!} -# Notarize Configuration +## Notarize Configuration -{% include "./app-builder-lib.Interface.NotarizeNotaryOptions.md" %} +{!./app-builder-lib.Interface.NotarizeNotaryOptions.md!} diff --git a/pages/mas.md b/pages/mas.md index 03defd415a4..925eb3bf7b7 100644 --- a/pages/mas.md +++ b/pages/mas.md @@ -1,7 +1,7 @@ The top-level [mas](configuration.md#Configuration-mas) key contains set of options instructing electron-builder on how it should build MAS (Mac Application Store) target. Inherits [macOS options](mac.md). -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.MasConfiguration.md" %} +{!./app-builder-lib.Interface.MasConfiguration.md!} diff --git a/pages/modules.md b/pages/modules.md deleted file mode 100644 index 36cd5fb05cd..00000000000 --- a/pages/modules.md +++ /dev/null @@ -1,12 +0,0 @@ -{% include "./app-builder-lib/globals.md" %} -{% include "./builder-util-runtime/globals.md" %} -{% include "./builder-util/globals.md" %} -{% include "./dmg-builder/globals.md" %} -{% include "./electron-builder-squirrel-windows/globals.md" %} -{% include "./electron-builder/globals.md" %} -{% include "./electron-forge-maker-appimage/globals.md" %} -{% include "./electron-forge-maker-nsis-web/globals.md" %} -{% include "./electron-forge-maker-nsis/globals.md" %} -{% include "./electron-forge-maker-snap/globals.md" %} -{% include "./electron-publish/globals.md" %} -{% include "./electron-updater/globals.md" %} diff --git a/pages/msi-wrapped.md b/pages/msi-wrapped.md index 9d9229aae39..8fce0f85fa4 100644 --- a/pages/msi-wrapped.md +++ b/pages/msi-wrapped.md @@ -1,3 +1,3 @@ -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.MsiWrappedOptions.md" %} \ No newline at end of file +{!./app-builder-lib.Interface.MsiWrappedOptions.md!} \ No newline at end of file diff --git a/pages/msi.md b/pages/msi.md index f87be642059..92f9e2aac05 100644 --- a/pages/msi.md +++ b/pages/msi.md @@ -1,3 +1,3 @@ -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.MsiOptions.md" %} \ No newline at end of file +{!./app-builder-lib.Interface.MsiOptions.md!} \ No newline at end of file diff --git a/pages/nsis.md b/pages/nsis.md index 3e32c7d6b6a..58b52a93462 100644 --- a/pages/nsis.md +++ b/pages/nsis.md @@ -149,6 +149,6 @@ For portable app, following environment variables are available: oneClick: false ``` -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.NsisOptions.md" %} +{!./app-builder-lib.Interface.NsisOptions.md!} diff --git a/pages/pkg.md b/pages/pkg.md index 9f70f218faf..37b18111371 100644 --- a/pages/pkg.md +++ b/pages/pkg.md @@ -1,5 +1,5 @@ The top-level [pkg](configuration.md#Configuration-pkg) key contains set of options instructing electron-builder on how it should build [PKG](https://goo.gl/yVvgF6) (macOS installer component package). -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.PkgOptions.md" %} \ No newline at end of file +{!./app-builder-lib.Interface.PkgOptions.md!} \ No newline at end of file diff --git a/pages/api/programmatic-usage.md b/pages/programmatic-usage.md similarity index 100% rename from pages/api/programmatic-usage.md rename to pages/programmatic-usage.md diff --git a/pages/publish.md b/pages/publish.md index db7ba6e204e..28a342ebeec 100644 --- a/pages/publish.md +++ b/pages/publish.md @@ -114,31 +114,31 @@ Detected automatically using: * or `CIRCLE_PROJECT_USERNAME`/`CIRCLE_PROJECT_REPONAME`, * if no env, from `.git/config` origin url. -# Publishers +## Publishers -# Bitbucket -{% include "./builder-util-runtime.Interface.BitbucketOptions.md" %} +## Bitbucket +{!./builder-util-runtime.Interface.BitbucketOptions.md!} -# Github +## Github -{% include "./builder-util-runtime.Interface.GithubOptions.md" %} +{!./builder-util-runtime.Interface.GithubOptions.md!} -# Keygen +## Keygen -{% include "./builder-util-runtime.Interface.KeygenOptions.md" %} +{!./builder-util-runtime.Interface.KeygenOptions.md!} -# S3 +## S3 -{% include "./builder-util-runtime.Interface.S3Options.md" %} +{!./builder-util-runtime.Interface.S3Options.md!} -# Snap Store +## Snap Store -{% include "./builder-util-runtime.Interface.SnapStoreOptions.md" %} +{!./builder-util-runtime.Interface.SnapStoreOptions.md!} -# Spaces +## Spaces -{% include "./builder-util-runtime.Interface.SpacesOptions.md" %} +{!./builder-util-runtime.Interface.SpacesOptions.md!} -# BYO Generic (create-your-own) +## BYO Generic (create-your-own) (And maybe submit it upstream in a PR!) -{% include "./builder-util-runtime.Interface.GenericServerOptions.md" %} \ No newline at end of file +{!./builder-util-runtime.Interface.GenericServerOptions.md!} \ No newline at end of file diff --git a/pages/snap.md b/pages/snap.md index adab38b789f..eaf56198017 100644 --- a/pages/snap.md +++ b/pages/snap.md @@ -1,5 +1,5 @@ The top-level [snap](configuration.md#Configuration-snap) key contains set of options instructing electron-builder on how it should build [Snap](http://snapcraft.io). -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.SnapOptions.md" %} \ No newline at end of file +{!./app-builder-lib.Interface.SnapOptions.md!} \ No newline at end of file diff --git a/pages/squirrel-windows.md b/pages/squirrel-windows.md index 0a2f3ae7754..42cca244309 100644 --- a/pages/squirrel-windows.md +++ b/pages/squirrel-windows.md @@ -7,6 +7,6 @@ To build for Squirrel.Windows on macOS, please install `mono` (`brew install mon Your app must be able to handle Squirrel.Windows startup events that occur during install and uninstall. See [electron-squirrel-startup](https://github.com/mongodb-js/electron-squirrel-startup). -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.SquirrelWindowsOptions.md" %} \ No newline at end of file +{!./app-builder-lib.Interface.SquirrelWindowsOptions.md!} \ No newline at end of file diff --git a/pages/stylesheets/autowidth.css b/pages/stylesheets/autowidth.css index 9b502bb4583..b736eb732b4 100644 --- a/pages/stylesheets/autowidth.css +++ b/pages/stylesheets/autowidth.css @@ -1,7 +1,10 @@ +/* Allow content to fill full width of browser window */ .md-main__inner.md-grid { max-width: initial; } - .md-grid { max-width: initial; } + +/* Hide TOC elements less than h3 */ +.md-nav--secondary .md-nav__list .md-nav__list .md-nav__list { display: none } \ No newline at end of file diff --git a/pages/tutorials/release-using-channels.md b/pages/tutorials/release-using-channels.md index 987195ee603..a6b238ab080 100644 --- a/pages/tutorials/release-using-channels.md +++ b/pages/tutorials/release-using-channels.md @@ -11,7 +11,7 @@ There are three channels, ordered by stability: 2. "beta" which means your application works, but should have some bugs (example: `1.3.2-beta`) 3. "alpha" which means your application is not stable and in active development (example: `1.3.2-alpha`) -## Configuration +### Configuration To release using channels, you should config electron-builder and define the channels to use in client side. ### Electron-Builder diff --git a/pages/win.md b/pages/win.md index d345b7438ae..86581603627 100644 --- a/pages/win.md +++ b/pages/win.md @@ -2,7 +2,7 @@ The top-level [win](configuration.md#Configuration-win) key contains set of opti --- -# Common Questions +## Common Questions ## How do delegate code signing? Use [sign](#WindowsConfiguration-sign) option. Please also see [why sign.js is called 8 times](https://github.com/electron-userland/electron-builder/issues/3995). @@ -92,6 +92,6 @@ The password to your VM is `Passw0rd!`. VirtualBox is not supported by electron-builder for now, so, you need to setup build environment on Windows if you want to use VirtualBox to build AppX (and other Windows-only tasks). -# Configuration +## Configuration -{% include "./app-builder-lib.Interface.WindowsConfiguration.md" %} +{!./app-builder-lib.Interface.WindowsConfiguration.md!} diff --git a/scripts/renderer/src/customRendererPlugin.ts b/scripts/renderer/src/customRendererPlugin.ts index 63a338ba7a1..b5cb4392fae 100644 --- a/scripts/renderer/src/customRendererPlugin.ts +++ b/scripts/renderer/src/customRendererPlugin.ts @@ -1,27 +1,99 @@ -import { Application, Renderer } from "typedoc"; -export const ALLOW_INHERIT_OPTIONS = "allowInheritedDoc"; +import { Application, Renderer } from "typedoc" + +import { Context, Converter, DeclarationReflection, Reflection, ReflectionKind } from "typedoc" export const load = (app: Application) => { - new FilterInheritPlugin(app).initialize() -}; + new NoInheritPlugin(app).initialize() +} class FilterInheritPlugin { - constructor(private readonly app: Application) { - } + constructor(private readonly app: Application) {} initialize() { - this.app.renderer.on(Renderer.EVENT_END_PAGE, async (context) => { + this.app.renderer.on(Renderer.EVENT_END_PAGE, async context => { // Filter out properties that are Inherited. It causes too much visual noise and there's already the Extends code block - const content = context.contents!.split("\n").reduce((prev, curr, _index, _arr) => { - const isInheritedProperty = /\|.*\[.*\]\(.*\).*\|/.test(curr); - if (!isInheritedProperty) { - return [...prev, curr] - } - return prev - }, [] as string[]).join("\n") + const content = context + .contents!.split("\n") + .reduce((prev, curr, _index, _arr) => { + const isInheritedProperty = /\|.*\[.*\]\(.*\).*\|/.test(curr) + if (!isInheritedProperty) { + return [...prev, curr] + } + return prev + }, [] as string[]) + .join("\n") // await mkdir(path.dirname(context.filename), { recursive: true }) // await writeFile(context.filename, content) }) } -} \ No newline at end of file +} + +/** + * A handler that deals with inherited reflections. + */ +export class NoInheritPlugin { + /** + * A list of reflections that are inherited from a super. + */ + private inheritedReflections: DeclarationReflection[] = [] + + constructor(private readonly app: Application) {} + initialize() { + this.app.converter.on(Converter.EVENT_BEGIN, this.onBegin.bind(this)) + this.app.converter.on(Converter.EVENT_CREATE_DECLARATION, this.onDeclaration.bind(this), -1100) // after ImplementsPlugin + this.app.converter.on(Converter.EVENT_RESOLVE_BEGIN, this.onBeginResolve.bind(this)) + } + + /** + * Triggered when the converter begins converting a project. + */ + private onBegin(context: Context) { + this.inheritedReflections = [] + } + + /** + * Triggered when the converter has created a declaration or signature reflection. + * Builds the list of classes/interfaces for the list of reflections that are inherited that could end up being removed. + */ + private onDeclaration(context: Context, reflection: Reflection) { + if (reflection instanceof DeclarationReflection) { + if ( + reflection.inheritedFrom && + reflection.parent && + reflection.parent.kindOf(ReflectionKind.ClassOrInterface) && + (!reflection.overwrites || (reflection.overwrites && reflection.overwrites !== reflection.inheritedFrom)) + ) { + this.inheritedReflections.push(reflection) + } + } + } + + /** + * Triggered when the converter begins resolving a project. + * Goes over the list of inherited reflections and removes any that are down the hierarchy + * from a class that doesn't inherit docs. + */ + private onBeginResolve(context: Context) { + const project = context.project + const removals: DeclarationReflection[] = [] + + this.inheritedReflections.forEach(reflection => { + if (this.isInherited(context, reflection)) { + removals.push(reflection) + } + }) + + removals.forEach(removal => { + project.removeReflection(removal) + }) + } + + private isInherited(context: Context, current: Reflection): boolean { + const parent = current.parent as DeclarationReflection + if (!parent) { + return false + } + return true + } +} diff --git a/scripts/renderer/src/typedoc2html.ts b/scripts/renderer/src/typedoc2html.ts index 94f7ec3d4b8..bfe0bf58ea5 100644 --- a/scripts/renderer/src/typedoc2html.ts +++ b/scripts/renderer/src/typedoc2html.ts @@ -1,42 +1,38 @@ -import { copy, exists } from "fs-extra"; -import { rm } from "fs/promises"; -import * as path from "path"; -import * as typedoc from "typedoc"; +import { copy, exists } from "fs-extra" +import { rm } from "fs/promises" +import * as path from "path" +import * as typedoc from "typedoc" async function main() { - - const outputDir = "docs"; + const outputDir = "docs" const dest = path.resolve(process.cwd(), outputDir) - const origin = path.resolve(process.cwd(), "pages"); + const origin = path.resolve(process.cwd(), "pages") console.log("copying from", origin, dest) - const siteDir = path.resolve(process.cwd(), "site"); - + const siteDir = path.resolve(process.cwd(), "site") - if ((await exists(siteDir))) { - await rm(siteDir,{ recursive: true }) + if (await exists(siteDir)) { + await rm(siteDir, { recursive: true }) } - if ((await exists(dest))) { + if (await exists(dest)) { await rm(dest, { recursive: true }) } await copy(origin, dest) - await copy(path.resolve("./README.md"), path.resolve(dest, "README.md")) + await copy(path.resolve(process.cwd(), "./README.md"), path.resolve(dest, "README.md")) const typedocConfig: Partial = { options: "typedoc.config.js", - }; + } const config = { ...typedocConfig, - flattenOutputFiles: true - }; + flattenOutputFiles: true, + } const app = await typedoc.Application.bootstrapWithPlugins(config) - const project = await app.convert(); + const project = await app.convert() - if (project) { - await app.generateDocs(project, outputDir); - } + await app.generateDocs(project!, outputDir) } -main().catch(console.error); +main().catch(console.error) diff --git a/test/README.md b/test/README.md index 58ac51ee519..88f3998f86b 100644 --- a/test/README.md +++ b/test/README.md @@ -2,5 +2,5 @@ Set environment variable `TEST_APP_TMP_DIR` (e.g. `/tmp/electron-builder-test`). Specified directory will be used instead of random temporary directory and *cleared* on each run. -# Test Code Signing Ceritificates +## Test Code Signing Ceritificates If test installer certificate is expired: http://security.stackexchange.com/questions/17909/how-to-create-an-apple-installer-package-signing-certificate \ No newline at end of file diff --git a/typedoc.config.js b/typedoc.config.js index 2542088f690..d9c75141871 100644 --- a/typedoc.config.js +++ b/typedoc.config.js @@ -8,10 +8,7 @@ module.exports = { entryPointStrategy: "packages", cleanOutputDir: false, flattenOutputFiles: true, - plugin: [ - "typedoc-plugin-markdown", - // "./scripts/renderer/out/customRendererPlugin.js", - ], + plugin: ["typedoc-plugin-markdown", "./scripts/renderer/out/customRendererPlugin.js"], excludeExternals: true, excludePrivate: true, excludeProtected: true, @@ -21,8 +18,11 @@ module.exports = { hidePageTitle: true, disableSources: true, hidePageHeader: true, - sort: ["required-first"], - categorizeByGroup: true, + useHTMLEncodedBrackets: true, + // groupOrder: ["source-order"], + // "readme": "none", + // "sort": ["kind"], + // "kindSortOrder": ["Function", "Interface", "TypeAlias"], // indexFormat: "table", // parametersFormat: "table", // interfacePropertiesFormat: "table",