🪵 1. TypeDoc 배포하기

TypeDoc

1. typedoc, typedoc-plugin-extras 설치

typedoc만 설치해줘도 문제 없지만 파비콘 같은 기타 속성들을 사용하기 위해 추가 플러그인도 설치해줬습니다.

pnpm add -D typedoc typedoc-plugin-extras

2. typedoc.json 작성

name: 배포 링크 제목
out: TypeDoc 내용이 담겨있는 html, css 문서가 저장될 디렉토리 경로
readme: 문서의 메인 페이지로 사용할 README 파일 경로
favicon: favicon 설정 (typedoc-plugin-extras 혹은 기타 플러그인 설치 필수)
plugin: 사용할 TypeDoc 플러그인 목록
entryPoints: 문서화할 TypeScript 파일들의 진입점 경로
exclude: 문서화에서 제외할 파일/디렉토리 패턴

{
  "name": "Webebeb Team's FE Tools Docs",
  "out": "./docs",
  "readme": "../README.md",
  "favicon": "./public/favicon.ico",
  "plugin": ["typedoc-plugin-extras"],
  "entryPoints": ["src/utils/index.ts", "src/hooks/index.ts"],
  "exclude": ["**/node_modules/**", "**/dist/**"]
}

3. TypeDoc 문서 자동 배포 GitHub Actions 워크플로우

main 또는 develop 브랜치에 push될 때 실행
pnpm과 Node.js(v18) 환경 설정 & 의존성 설치
TypeDoc으로 문서 빌드
GitHub Pages로 문서 배포 (./client/docs → gh-pages 브랜치)

name: Deploy Documentation

on:
  push:
    branches: ['main', 'develop']
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    defaults:
      run:
        working-directory: ./client

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8
          run_install: false

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'pnpm'
          cache-dependency-path: './client/pnpm-lock.yaml'

      - name: Install dependencies
        working-directory: ./client
        run: pnpm install

      - name: Build documentation
        run: pnpm typedoc

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./client/docs
          force_orphan: true
          commit_message: 'docs: deploy documentation'

4. 실제 문서 테스트

Github pages로 문서 배포를 원한다면 꼭꼭 앞에 workflow 세팅까지 선행되어야 합니다.
TypeDoc이 JSDoc 주석을 파싱하여 문서화 해줍니다.
또한 vscode에서 작업할 때도 해당 함수에 마우스 호버 시 example 등을 미리 볼 수 있어 유용합니다.

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

/**
 * Tailwind CSS 클래스들을 병합하는 유틸리티 함수입니다.
 *
 * - clsx를 사용하여 조건부 클래스를 처리합니다.
 * - tailwind-merge를 사용하여 Tailwind 클래스 충돌을 해결합니다.
 *
 * @param inputs - 병합할 클래스들의 배열. ClassValue 타입은 문자열, 객체, 배열 등을 포함할 수 있습니다.
 * @returns 병합된 클래스 문자열
 *
 * @example
 * ```tsx
 * // 버튼 컴포넌트에서의 사용 예시
 * const buttonVariants = cva(
 *   'inline-flex items-center justify-center',
 *   {
 *     variants: {
 *       variant: {
 *         primary: 'bg-violet-500 hover:bg-violet-600',
 *         // ...
 *       },
 *       size: {
 *         sm: 'h-11 text-2xl',
 *         // ...
 *       }
 *     },
 *     defaultVariants: {
 *       variant: 'primary',
 *       size: 'sm'
 *     }
 *   }
 * );
 *
 * const Button = ({ className, variant, size, ...props }) => {
 *   return (
 *     <button
 *       className={cn(
 *         buttonVariants({ variant, size, className }),
 *       )}
 *       {...props}
 *     />
 *   );
 * };
 * ```
 *
 * @see {@link https://github.com/lukeed/clsx clsx}
 * @see {@link https://github.com/dcastil/tailwind-merge tailwind-merge}
 * @see {@link https://github.com/shadcn/ui shadcn/ui}
 * @category Utils
 */
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}