Skip to content

Commit

Permalink
refactor: docs design (#8487)
Browse files Browse the repository at this point in the history
  • Loading branch information
@iCrawl
iCrawl committed Aug 15, 2022
1 parent d09ef1e commit 4ab1d09
Show file tree
Hide file tree
Showing 44 changed files with 1,536 additions and 1,254 deletions.
4 changes: 2 additions & 2 deletions packages/actions/package.json
View file
Expand Up @@ -6,8 +6,8 @@
"scripts": {
"test": "vitest run",
"build": "unbuild",
"lint": "prettier --check . && eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && eslint src __tests__ --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src __tests__ --ext mjs,js,ts --fix",
"fmt": "yarn format"
},
"main": "./dist/index.mjs",
Expand Down
4 changes: 2 additions & 2 deletions packages/builders/package.json
View file
Expand Up @@ -5,8 +5,8 @@
"scripts": {
"test": "vitest run",
"build": "unbuild",
"lint": "prettier --check . && eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && eslint src __tests__ --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src __tests__ --ext mjs,js,ts --fix",
"fmt": "yarn format",
"docs": "downlevel-dts . docs --to=3.7 && docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn lint && yarn test && yarn build",
Expand Down
4 changes: 2 additions & 2 deletions packages/collection/package.json
View file
Expand Up @@ -5,8 +5,8 @@
"scripts": {
"test": "vitest run",
"build": "unbuild",
"lint": "prettier --check . && eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && eslint src __tests__ --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src __tests__ --ext mjs,js,ts --fix",
"fmt": "yarn format",
"docs": "downlevel-dts . docs --to=3.7 && docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn lint && yarn test && yarn build",
Expand Down
8 changes: 4 additions & 4 deletions packages/docgen/package.json
View file
Expand Up @@ -4,8 +4,8 @@
"description": "The docs.json generator for discord.js and its related projects",
"scripts": {
"build": "unbuild",
"lint": "prettier --check . && eslint src --ext mjs,js,ts",
"format": "prettier --write . && eslint src --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src --ext mjs,js,ts --fix",
"fmt": "yarn format",
"prepack": "yarn format && yarn build",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/docgen/*'",
Expand Down Expand Up @@ -50,7 +50,7 @@
"devDependencies": {
"@favware/cliff-jumper": "^1.8.6",
"@types/jsdoc-to-markdown": "^7.0.3",
"@types/node": "^16.11.47",
"@types/node": "^16.11.48",
"@typescript-eslint/eslint-plugin": "^5.33.0",
"@typescript-eslint/parser": "^5.33.0",
"eslint": "^8.22.0",
Expand All @@ -61,7 +61,7 @@
"prettier": "^2.7.1",
"rollup-plugin-typescript2": "0.32.1",
"typescript": "^4.7.4",
"unbuild": "^0.8.4"
"unbuild": "^0.8.8"
},
"engines": {
"node": ">=16.9.0"
Expand Down
4 changes: 2 additions & 2 deletions packages/proxy-container/package.json
View file
Expand Up @@ -4,8 +4,8 @@
"description": "Lightweight HTTP proxy for Discord's API, brought to you as a container 📦",
"scripts": {
"build": "unbuild",
"lint": "prettier --check . && eslint src --ext mjs,js,ts",
"format": "prettier --write . && eslint src --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src --ext mjs,js,ts --fix",
"fmt": "yarn format",
"prepack": "yarn lint && yarn test && yarn build",
"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/proxy-container/*'"
Expand Down
4 changes: 2 additions & 2 deletions packages/proxy/package.json
View file
Expand Up @@ -5,8 +5,8 @@
"scripts": {
"test": "vitest run",
"build": "unbuild",
"lint": "prettier --check . && eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && eslint src __tests__ --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src __tests__ --ext mjs,js,ts --fix",
"fmt": "yarn format",
"docs": "downlevel-dts . docs --to=3.7 && docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn lint && yarn test && yarn build",
Expand Down
4 changes: 2 additions & 2 deletions packages/rest/package.json
View file
Expand Up @@ -5,8 +5,8 @@
"scripts": {
"test": "vitest run",
"build": "unbuild",
"lint": "prettier --check . && eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && eslint src __tests__ --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src __tests__ --ext mjs,js,ts --fix",
"fmt": "yarn format",
"docs": "downlevel-dts . docs --to=3.7 && docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn lint && yarn test && yarn build",
Expand Down
4 changes: 2 additions & 2 deletions packages/scripts/package.json
View file
Expand Up @@ -6,8 +6,8 @@
"scripts": {
"test": "vitest run",
"build": "unbuild",
"lint": "prettier --check . && eslint src --ext mjs,js,ts",
"format": "prettier --write . && eslint src --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src --ext mjs,js,ts --fix",
"fmt": "yarn format"
},
"main": "./dist/index.cjs",
Expand Down
4 changes: 2 additions & 2 deletions packages/voice/package.json
View file
Expand Up @@ -5,8 +5,8 @@
"scripts": {
"build": "unbuild",
"test": "jest --coverage",
"lint": "prettier --check . && eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && eslint src __tests__ --ext mjs,js,ts --fix",
"lint": "prettier --check . && TIMING=1 eslint src __tests__ --ext mjs,js,ts",
"format": "prettier --write . && TIMING=1 eslint src __tests__ --ext mjs,js,ts --fix",
"fmt": "yarn format",
"docs": "downlevel-dts . docs --to=3.7 && docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
"prepack": "yarn lint && yarn test && yarn build",
Expand Down
16 changes: 9 additions & 7 deletions packages/website/package.json
View file
Expand Up @@ -12,8 +12,8 @@
"dev:next": "next dev",
"dev:css": "yarn generate:css --watch",
"generate:css": "unocss 'src/**/*.tsx' --out-file ./src/styles/unocss.css",
"lint": "prettier --check . && eslint src --ext mjs,js,ts,tsx",
"format": "prettier --write . && eslint src --ext mjs,js,ts,tsx --fix"
"lint": "prettier --check . && TIMING=1 eslint src --ext mjs,js,ts,tsx",
"format": "prettier --write . && TIMING=1 eslint src --ext mjs,js,ts,tsx --fix"
},
"main": "./dist/index.js",
"module": "./dist/index.mjs",
Expand Down Expand Up @@ -47,11 +47,17 @@
},
"homepage": "https://discord.js.org",
"dependencies": {
"@emotion/react": "^11.10.0",
"@emotion/server": "^11.10.0",
"@mantine/core": "^5.1.6",
"@mantine/hooks": "^5.1.6",
"@mantine/next": "^5.1.6",
"@mantine/nprogress": "^5.1.6",
"@mantine/spotlight": "^5.1.6",
"@microsoft/api-extractor-model": "^7.23.0",
"@microsoft/tsdoc": "0.14.1",
"@microsoft/tsdoc-config": "0.16.1",
"@vscode/codicons": "^0.0.32",
"framer-motion": "^7.1.0",
"next": "^12.2.5",
"react": "^18.2.0",
"react-dom": "^18.2.0",
Expand All @@ -60,9 +66,6 @@
"sharp": "^0.30.7"
},
"devDependencies": {
"@testing-library/cypress": "^8.0.3",
"@testing-library/dom": "^8.17.1",
"@testing-library/jest-dom": "^5.16.5",
"@testing-library/react": "^13.3.0",
"@testing-library/user-event": "^14.4.3",
"@types/node": "^16.11.48",
Expand All @@ -85,7 +88,6 @@
"eslint-plugin-react": "^7.30.1",
"eslint-plugin-react-hooks": "^4.6.0",
"happy-dom": "^6.0.4",
"msw": "^0.44.2",
"prettier": "^2.7.1",
"typescript": "^4.7.4",
"unocss": "^0.45.6",
Expand Down
46 changes: 22 additions & 24 deletions packages/website/src/components/CodeListing.tsx
View file
@@ -1,3 +1,4 @@
import { Group, Stack, Title } from '@mantine/core';
import type { ReactNode } from 'react';
import { CommentSection } from './Comment';
import { HyperlinkedText } from './HyperlinkedText';
Expand All @@ -9,36 +10,33 @@ export enum CodeListingSeparatorType {
Value = '=',
}

export interface CodeListingProps {
name: string;
summary?: ReturnType<DocItem['toJSON']>['summary'];
typeTokens: TokenDocumentation[];
separator?: CodeListingSeparatorType;
children?: ReactNode;
className?: string | undefined;
}

export function CodeListing({
name,
className,
separator = CodeListingSeparatorType.Type,
summary,
typeTokens,
children,
}: CodeListingProps) {
}: {
name: string;
summary?: ReturnType<DocItem['toJSON']>['summary'];
typeTokens: TokenDocumentation[];
separator?: CodeListingSeparatorType;
children?: ReactNode;
className?: string | undefined;
}) {
return (
<div className={className}>
<div key={name} className="flex flex-col">
<div className="w-full flex flex-row gap-3">
<h4 className="font-mono m-0">{`${name}`}</h4>
<h4 className="m-0">{separator}</h4>
<h4 className="font-mono m-0 break-all">
<HyperlinkedText tokens={typeTokens} />
</h4>
</div>
{summary && <CommentSection textClassName="text-dark-100 dark:text-gray-300" node={summary} />}
{children}
</div>
</div>
<Stack key={name}>
<Group>
<Title order={4} className="font-mono">
{name}
</Title>
<Title order={4}>{separator}</Title>
<Title order={4} className="font-mono break-all">
<HyperlinkedText tokens={typeTokens} />
</Title>
</Group>
{summary && <CommentSection node={summary} />}
{children}
</Stack>
);
}
54 changes: 39 additions & 15 deletions packages/website/src/components/Comment.tsx
View file
@@ -1,46 +1,70 @@
import { Anchor, Box, Text } from '@mantine/core';
import Link from 'next/link';
import type { ReactNode } from 'react';
import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
import type { CommentNode } from '~/DocModel/comment/CommentNode';
import type { CommentNodeContainer } from '~/DocModel/comment/CommentNodeContainer';
import type { FencedCodeCommentNode } from '~/DocModel/comment/FencedCodeCommentNode';
import type { LinkTagCommentNode } from '~/DocModel/comment/LinkTagCommentNode';
import type { PlainTextCommentNode } from '~/DocModel/comment/PlainTextCommentNode';

export interface RemarksBlockProps {
node: ReturnType<CommentNode['toJSON']>;
textClassName?: string | undefined;
}

export function CommentSection({ node, textClassName }: RemarksBlockProps): JSX.Element {
export function CommentSection({ node }: { node: ReturnType<CommentNode['toJSON']> }): JSX.Element {
const createNode = (node: ReturnType<CommentNode['toJSON']>, idx?: number): ReactNode => {
switch (node.kind) {
case 'PlainText':
return <span key={idx}>{(node as ReturnType<PlainTextCommentNode['toJSON']>).text}</span>;
return (
<Text key={idx} span>
{(node as ReturnType<PlainTextCommentNode['toJSON']>).text}
</Text>
);
case 'Paragraph':
return (
<p key={idx} className={textClassName}>
<Text key={idx} inline>
{(node as ReturnType<CommentNodeContainer['toJSON']>).nodes.map((node, idx) => createNode(node, idx))}
</p>
</Text>
);
case 'SoftBreak':
return <br key={idx} />;
case 'LinkTag': {
const { codeDestination, urlDestination, text } = node as ReturnType<LinkTagCommentNode['toJSON']>;

if (codeDestination) {
return <Link href={codeDestination.path}>{text ?? codeDestination.name}</Link>;
return (
<Link key={idx} href={codeDestination.path} passHref>
<Anchor component="a" className="font-mono">
{text ?? codeDestination.name}
</Anchor>
</Link>
);
}

if (urlDestination) {
return <Link href={urlDestination}>{text ?? urlDestination}</Link>;
return (
<Link key={idx} href={urlDestination} passHref>
<Anchor component="a" className="font-mono">
{text ?? urlDestination}
</Anchor>
</Link>
);
}

return null;
}
case 'FencedCodeBlock': {
const { language, code } = node as ReturnType<FencedCodeCommentNode['toJSON']>;
return <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>;
return (
<SyntaxHighlighter
key={idx}
wrapLines
wrapLongLines
language={language}
style={vscDarkPlus}
codeTagProps={{ style: { fontFamily: 'JetBrains Mono' } }}
>
{code}
</SyntaxHighlighter>
);
}
default:
break;
Expand All @@ -50,12 +74,12 @@ export function CommentSection({ node, textClassName }: RemarksBlockProps): JSX.
};

return (
<div>
<Box>
{node.kind === 'Paragraph' || node.kind === 'Section' ? (
<>{(node as CommentNodeContainer).nodes.map((node, idx) => createNode(node, idx))}</>
) : (
<>{createNode(node)}</>
createNode(node)
)}
</div>
</Box>
);
}

1 comment on commit 4ab1d09

@vercel
Copy link

@vercel vercel bot commented on 4ab1d09 Aug 15, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

discord-js – ./

discordjs.dev
discord-js-number-one.vercel.app
discord-js-discordjs.vercel.app
discord-js-git-main-discordjs.vercel.app
www.discordjs.dev

Please sign in to comment.