feat(website): add support for source file links (#9048)

Co-authored-by: Noel <buechler.noel@outlook.com>
discordjs · Jan 12, 2023 · f6506e9 · f6506e9 · vercel · Jan 12, 2023
1 parent a580768
commit f6506e9
Show file tree

Hide file tree

Showing 32 changed files with 333 additions and 245 deletions.
diff --git a/.gitignore b/.gitignore
@@ -16,6 +16,7 @@ pids
 
 # Dist
 dist/
+dist-docs/
 
 # Miscellaneous
 .tmp/

diff --git a/...-tsdoc-config-npm-0.16.1-81031b1bbf.patch → ...-tsdoc-config-npm-0.16.2-81031b1bbf.patch b/...-tsdoc-config-npm-0.16.1-81031b1bbf.patch → ...-tsdoc-config-npm-0.16.2-81031b1bbf.patch
diff --git a/api-extractor.json b/api-extractor.json
@@ -45,7 +45,7 @@
 	 *
 	 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
 	 */
-	"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+	"mainEntryPointFilePath": "<projectFolder>/dist-docs/index.d.ts",
 
 	/**
 	 * A list of NPM package names whose exports should be treated as part of this package.

diff --git a/apps/website/package.json b/apps/website/package.json
@@ -46,8 +46,8 @@
 		"@discordjs/api-extractor-utils": "workspace:^",
 		"@discordjs/scripts": "workspace:^",
 		"@discordjs/ui": "workspace:^",
-		"@microsoft/api-extractor-model": "7.24.0",
-		"@microsoft/tsdoc": "0.14.1",
+		"@microsoft/api-extractor-model": "7.25.3",
+		"@microsoft/tsdoc": "0.14.2",
 		"@react-icons/all-files": "^4.1.0",
 		"@vercel/og": "^0.0.26",
 		"@vscode/codicons": "^0.0.32",
@@ -62,7 +62,7 @@
 		"react-dom": "^18.2.0",
 		"react-syntax-highlighter": "^15.5.0",
 		"react-use": "^17.4.0",
-		"rehype-ignore": "^1.0.3",
+		"rehype-ignore": "^1.0.4",
 		"rehype-pretty-code": "^0.8.1",
 		"rehype-raw": "^6.1.1",
 		"rehype-slug": "^5.1.0",

diff --git a/apps/website/src/components/documentation/Header.tsx b/apps/website/src/components/documentation/Header.tsx
@@ -1,4 +1,5 @@
 import { ApiItemKind } from '@microsoft/api-extractor-model';
+import { VscFileCode } from '@react-icons/all-files/vsc/VscFileCode';
 import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
 import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
 import { VscSymbolInterface } from '@react-icons/all-files/vsc/VscSymbolInterface';
@@ -24,12 +25,23 @@ function generateIcon(kind: ApiItemKind) {
 	}
 }
 
-export function Header({ kind, name }: PropsWithChildren<{ kind: ApiItemKind; name: string }>) {
+export function Header({
+	kind,
+	name,
+	sourceURL,
+}: PropsWithChildren<{ kind: ApiItemKind; name: string; sourceURL?: string | undefined }>) {
 	return (
 		<div className="flex flex-col">
-			<h2 className="flex flex-row place-items-center gap-2 break-all text-2xl font-bold">
-				<span>{generateIcon(kind)}</span>
-				{name}
+			<h2 className="flex flex-row place-items-center justify-between gap-2 break-all text-2xl font-bold">
+				<span className="row flex flex place-items-center gap-2">
+					<span>{generateIcon(kind)}</span>
+					{name}
+				</span>
+				{sourceURL ? (
+					<a className="text-blurple" href={sourceURL}>
+						<VscFileCode />
+					</a>
+				) : null}
 			</h2>
 		</div>
 	);

diff --git a/apps/website/src/components/documentation/ObjectHeader.tsx b/apps/website/src/components/documentation/ObjectHeader.tsx
@@ -10,7 +10,7 @@ export interface ObjectHeaderProps {
 export function ObjectHeader({ item }: ObjectHeaderProps) {
 	return (
 		<>
-			<Header kind={item.kind} name={item.displayName} />
+			<Header kind={item.kind} name={item.displayName} sourceURL={item.sourceLocation.fileUrl} />
 			<SyntaxHighlighter code={item.excerpt.text} />
 			<SummarySection item={item} />
 		</>

diff --git a/package.json b/package.json
@@ -61,7 +61,7 @@
 		"vitest": "^0.27.1"
 	},
 	"resolutions": {
-		"@microsoft/tsdoc-config": "patch:@microsoft/tsdoc-config@npm:0.16.1#.yarn/patches/@microsoft-tsdoc-config-npm-0.16.1-81031b1bbf.patch"
+		"@microsoft/tsdoc-config": "patch:@microsoft/tsdoc-config@npm:0.16.2#.yarn/patches/@microsoft-tsdoc-config-npm-0.16.2-81031b1bbf.patch"
 	},
 	"engines": {
 		"node": ">=16.9.0"

diff --git a/packages/api-extractor-utils/package.json b/packages/api-extractor-utils/package.json
@@ -31,8 +31,8 @@
 	},
 	"homepage": "https://discord.js.org",
 	"dependencies": {
-		"@microsoft/api-extractor-model": "7.24.0",
-		"@microsoft/tsdoc": "0.14.1"
+		"@microsoft/api-extractor-model": "7.25.3",
+		"@microsoft/tsdoc": "0.14.2"
 	},
 	"devDependencies": {
 		"@types/node": "16.18.11",

diff --git a/packages/brokers/api-extractor.json b/packages/brokers/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/brokers"
+	}
 }
diff --git a/packages/brokers/package.json b/packages/brokers/package.json
@@ -5,10 +5,11 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/brokers/*'",
 		"release": "cliff-jumper"

diff --git a/packages/builders/api-extractor.json b/packages/builders/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/builders"
+	}
 }
diff --git a/packages/builders/package.json b/packages/builders/package.json
@@ -5,10 +5,11 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\" && yarn downlevel-dts ./dist-docs ./dist-docs",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/builders/*'",
 		"release": "cliff-jumper"
@@ -68,6 +69,7 @@
 		"@types/node": "16.18.11",
 		"@vitest/coverage-c8": "^0.27.1",
 		"cross-env": "^7.0.3",
+		"downlevel-dts": "^0.11.0",
 		"esbuild-plugin-version-injector": "^1.0.2",
 		"eslint": "^8.31.0",
 		"eslint-config-neon": "^0.1.40",

diff --git a/packages/collection/api-extractor.json b/packages/collection/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/collection"
+	}
 }
diff --git a/packages/collection/package.json b/packages/collection/package.json
@@ -5,13 +5,15 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/collection/*'",
-		"release": "cliff-jumper"
+		"release": "cliff-jumper",
+		"docs:declarations": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist\""
 	},
 	"main": "./dist/index.js",
 	"module": "./dist/index.mjs",

diff --git a/packages/core/api-extractor.json b/packages/core/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/core"
+	}
 }
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -5,9 +5,10 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src --ext .mjs,.js,.ts --fix --format=pretty",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn build && yarn lint",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/core/*'",
 		"release": "cliff-jumper"

diff --git a/packages/formatters/api-extractor.json b/packages/formatters/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/formatters"
+	}
 }
diff --git a/packages/formatters/package.json b/packages/formatters/package.json
@@ -5,9 +5,10 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn build && yarn lint",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/formatters/*'",
 		"release": "cliff-jumper"

diff --git a/packages/next/api-extractor.json b/packages/next/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/next"
+	}
 }
diff --git a/packages/next/package.json b/packages/next/package.json
@@ -5,9 +5,10 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn build && yarn lint",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/next/*'",
 		"release": "cliff-jumper"

diff --git a/packages/proxy/api-extractor.json b/packages/proxy/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/proxy"
+	}
 }
diff --git a/packages/proxy/package.json b/packages/proxy/package.json
@@ -5,10 +5,11 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/proxy/*'",
 		"release": "cliff-jumper"

diff --git a/packages/rest/api-extractor.json b/packages/rest/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/rest"
+	}
 }
diff --git a/packages/rest/package.json b/packages/rest/package.json
@@ -5,10 +5,11 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/rest/*'",
 		"release": "cliff-jumper"

diff --git a/packages/scripts/package.json b/packages/scripts/package.json
@@ -44,9 +44,9 @@
 	"homepage": "https://discord.js.org",
 	"dependencies": {
 		"@discordjs/api-extractor-utils": "workspace:^",
-		"@microsoft/api-extractor-model": "7.24.0",
-		"@microsoft/tsdoc": "0.14.1",
-		"@microsoft/tsdoc-config": "0.16.1",
+		"@microsoft/api-extractor-model": "7.25.3",
+		"@microsoft/tsdoc": "0.14.2",
+		"@microsoft/tsdoc-config": "0.16.2",
 		"commander": "^9.5.0",
 		"fs-extra": "^11.1.0",
 		"tslib": "^2.4.1",

diff --git a/packages/util/api-extractor.json b/packages/util/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/util"
+	}
 }
diff --git a/packages/util/package.json b/packages/util/package.json
@@ -4,11 +4,12 @@
 	"description": "Utilities shared across Discord.js packages",
 	"scripts": {
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"test": "vitest run && tsd",
 		"lint": "prettier --check . && TIMING=1 eslint src --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && TIMING=1 eslint src --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/util/*'",
 		"release": "cliff-jumper"

diff --git a/packages/voice/api-extractor.json b/packages/voice/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/voice"
+	}
 }
diff --git a/packages/voice/package.json b/packages/voice/package.json
@@ -4,11 +4,12 @@
 	"description": "Implementation of the Discord Voice API for node.js",
 	"scripts": {
 		"build": "tsup && node scripts/postbuild.mjs",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"test": "jest --coverage",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
 		"fmt": "yarn format",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn lint && yarn test && yarn build",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/voice/*'",
 		"release": "cliff-jumper"

diff --git a/packages/ws/api-extractor.json b/packages/ws/api-extractor.json
@@ -1,3 +1,6 @@
 {
-	"extends": "../../api-extractor.json"
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"projectFolderUrl": "https://github.com/discordjs/discord.js/tree/main/packages/ws"
+	}
 }
diff --git a/packages/ws/package.json b/packages/ws/package.json
@@ -5,9 +5,10 @@
 	"scripts": {
 		"test": "vitest run",
 		"build": "tsup",
+		"build:docs": "tsc --emitDeclarationOnly --declarationMap --skipLibCheck --outDir \"dist-docs\"",
 		"lint": "prettier --check . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --format=pretty",
 		"format": "prettier --write . && cross-env TIMING=1 eslint src __tests__ --ext .mjs,.js,.ts --fix --format=pretty",
-		"docs": "api-extractor run --local",
+		"docs": "yarn build:docs && api-extractor run --local",
 		"prepack": "yarn build && yarn lint",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/ws/*'",
 		"release": "cliff-jumper"