From c799d3ab42779ba1fa006a767568e1625fd93195 Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Mon, 10 Jun 2024 11:40:48 -0700 Subject: [PATCH 1/2] docs: clean up typedoc output --- package.json | 4 ++-- src/packager.ts | 2 +- src/types.ts | 47 ++++++++++++++++++++++++++++++------------- test/ci/build_docs.js | 41 ------------------------------------- typedoc.json | 14 +++++++++++++ yarn.lock | 2 +- 6 files changed, 51 insertions(+), 59 deletions(-) delete mode 100755 test/ci/build_docs.js create mode 100644 typedoc.json diff --git a/package.json b/package.json index 101b65b2..7298d572 100644 --- a/package.json +++ b/package.json @@ -69,7 +69,7 @@ "nyc": "^15.0.0", "pkg-up": "^4.0.0", "sinon": "^17.0.0", - "typedoc": "^0.25.4", + "typedoc": "~0.25.4", "typescript": "^5.2.2" }, "engines": { @@ -81,7 +81,7 @@ "postbuild": "copyfiles -f ./temp/targets.js ./src", "codecov": "nyc report --reporter=text-lcov > coverage.lcov && codecov", "coverage": "nyc ava test/index.js", - "docs:build": "node test/ci/build_docs.js", + "docs:build": "npx typedoc", "lint": "eslint --ext .ts .", "prepublish": "npm run build", "pretest": "npm run build", diff --git a/src/packager.ts b/src/packager.ts index 82889103..f4ee1ca6 100644 --- a/src/packager.ts +++ b/src/packager.ts @@ -192,7 +192,7 @@ async function packageAllSpecifiedCombos(opts: Options, archs: SupportedArch[], * - finds or downloads the correct release of Electron * - uses that version of Electron to create a app in `/--` * - * Short example: + * @example * * ```javascript * const packager = require('@electron/packager') diff --git a/src/types.ts b/src/types.ts index 1007b1a4..04eef324 100644 --- a/src/types.ts +++ b/src/types.ts @@ -15,6 +15,9 @@ import { SignOptions as OSXInternalSignOptions } from '@electron/osx-sign/dist/e import { SignOptions as WindowsInternalSignOptions } from '@electron/windows-sign/dist/esm/types'; import type { makeUniversalApp } from '@electron/universal'; +/** + * @internal + */ export type MakeUniversalOpts = Parameters[0] /** @@ -48,7 +51,7 @@ export type SupportedPlatform = OfficialPlatform | 'all'; /** * A predicate function that, given an absolute file `path`, returns `true` if the file should be * ignored, or `false` if the file should be kept. *This does not use any of the default ignored - * files/directories listed for the {@link ignore} option.* + * files/directories listed for the {@link Options.ignore | ignore} option.* */ export type IgnoreFunction = (path: string) => boolean; @@ -61,7 +64,18 @@ export type HookFunctionErrorCallback = (err?: Error | null) => void * By default, the functions are called in parallel (via * [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)). * If you need the functions called serially, there is a utility function provided. Please note that - * **callback-style functions are not supported by `serialHooks`.** For example: + * **callback-style functions are not supported by `serialHooks`.** + * + * @param buildPath - For {@link Options.afterExtract | afterExtract}, the path to the temporary folder where the prebuilt + * Electron binary has been extracted to. For {@link Options.afterCopy | afterCopy} and {@link Options.afterPrune | afterPrune}, the path to the + * folder where the Electron app has been copied to. For {@link Options.afterComplete | afterComplete}, the final directory + * of the packaged application. + * @param electronVersion - the version of Electron that is being bundled with the application. + * @param platform - The target platform you are packaging for. + * @param arch - The target architecture you are packaging for. + * @param callback - Must be called once you have completed your actions. + * + * @example * * ```javascript * const packager = require('@electron/packager') @@ -90,16 +104,6 @@ export type HookFunctionErrorCallback = (err?: Error | null) => void * plugins](https://github.com/electron/packager#plugins). */ export type HookFunction = -/** - * @param buildPath - For {@link afterExtract}, the path to the temporary folder where the prebuilt - * Electron binary has been extracted to. For {@link afterCopy} and {@link afterPrune}, the path to the - * folder where the Electron app has been copied to. For {@link afterComplete}, the final directory - * of the packaged application. - * @param electronVersion - the version of Electron that is being bundled with the application. - * @param platform - The target platform you are packaging for. - * @param arch - The target architecture you are packaging for. - * @param callback - Must be called once you have completed your actions. - */ ( buildPath: string, electronVersion: string, @@ -114,15 +118,21 @@ export type TargetDefinition = { } export type FinalizePackageTargetsHookFunction = (targets: TargetDefinition[], callback: HookFunctionErrorCallback) => void; -/** See the documentation for [`@electron/osx-sign`](https://npm.im/@electron/osx-sign#opts) for details. */ +/** See the documentation for [`@electron/osx-sign`](https://npm.im/@electron/osx-sign#opts) for details. + * @interface + */ export type OsxSignOptions = Omit; /** * See the documentation for [`@electron/universal`](https://github.com/electron/universal) * for details. + * @interface */ export type OsxUniversalOptions = Omit +/** + * @internal + */ export type IgnoreFunc = (platform: string, arch: string) => boolean; /** @@ -516,7 +526,7 @@ export interface Options { * - `mas` (macOS, specifically for submitting to the Mac App Store) * - `win32` */ - platform?: PlatformOption | PlatformOption[]; + platform?: TargetPlatform | 'all' | Array; /** * The path to a prebuilt ASAR file. * @@ -598,16 +608,25 @@ export interface Options { windowsSign?: true | WindowsSignOptions; } +/** + * @internal + */ interface OptionsWithRequiredArchAndPlatform extends Options { arch: Exclude; platform: Exclude; } +/** + * @internal + */ export interface DownloadOptions extends OptionsWithRequiredArchAndPlatform { artifactName: string; version: string; } +/** + * @internal + */ export interface ComboOptions extends Options { arch: OptionsWithRequiredArchAndPlatform['arch'] platform: OptionsWithRequiredArchAndPlatform['platform'] diff --git a/test/ci/build_docs.js b/test/ci/build_docs.js deleted file mode 100755 index bda17d71..00000000 --- a/test/ci/build_docs.js +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env node -'use strict' - -const { Application } = require('typedoc') - -/** @type import('typedoc').TypeDocOptions */ -const config = { - excludeExternals: true, - excludePrivate: true, - excludeProtected: true, - entryPoints: ['src/index.ts'] -} - -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 - } -} - -Application.bootstrap(config).then(async app => { - const project = await app.convert() - if (project) { - await app.generateDocs(project, 'typedoc') - } else { - console.error('Could not generate API documentation from TypeScript definition!') - process.exit(1) - } -}) - diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 00000000..53d14958 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,14 @@ +{ + "entryPoints": ["src/index.ts"], + "out": "./typedoc", + "excludeInternal": true, + "sort": ["kind", "required-first", "alphabetical"], + "externalSymbolLinkMappings": { + "@electron/notarize": { + "NotaryToolCredentials": "https://erickzhao.github.io/notarize/types/NotaryToolCredentials.html" + }, + "@electron/get": { + "ElectronDownloadRequestOptions": "https://github.com/electron/get/blob/79dab2b26df3a6841062b676f11d3e7bb1f8995e/src/types.ts#L57" + } + } +} \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index eb25b0b8..8273707b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4620,7 +4620,7 @@ typedarray-to-buffer@^3.1.5: dependencies: is-typedarray "^1.0.0" -typedoc@^0.25.4: +typedoc@~0.25.4: version "0.25.13" resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.13.tgz#9a98819e3b2d155a6d78589b46fa4c03768f0922" integrity sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ== From a83a8b3257148f20ef191084aadf193e4a004085 Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Mon, 10 Jun 2024 11:43:41 -0700 Subject: [PATCH 2/2] fix links --- src/types.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/types.ts b/src/types.ts index 04eef324..38d0a143 100644 --- a/src/types.ts +++ b/src/types.ts @@ -266,7 +266,7 @@ export interface Options { * Arbitrary combinations of individual architectures are also supported via a comma-delimited * string or array of strings. The non-`all` values correspond to the architecture names used * by [Electron releases](https://github.com/electron/electron/releases). This value - * is not restricted to the official set if [[download|`download.mirrorOptions`]] is set. + * is not restricted to the official set if {@link download|`download.mirrorOptions`} is set. * * Defaults to the arch of the host computer running Electron Packager. * @@ -427,7 +427,7 @@ export interface Options { * to show up in the dock/window list.* Setting the icon in the file manager is not currently supported. * * If the file extension is omitted, it is auto-completed to the correct extension based on the - * platform, including when [[platform|`platform: 'all'`]] is in effect. + * platform, including when {@link platform |`platform: 'all'`} is in effect. */ icon?: string; /** @@ -516,7 +516,7 @@ export interface Options { * * The official non-`all` values correspond to the platform names used by [Electron * releases](https://github.com/electron/electron/releases). This value is not restricted to - * the official set if [[download|`download.mirrorOptions]] is set. + * the official set if {@link download|`download.mirrorOptions`} is set. * * Defaults to the platform of the host computer running Electron Packager. * @@ -579,7 +579,7 @@ export interface Options { * Valid properties are the [Cocoa keys for MacOS](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html) * of the pattern `NS(.*)UsageDescription`, where the captured group is the key to use. * - * Example: + * @example * * ```javascript * {