[NestJS] 자동 문서화 가이드 (Compodoc)

개발자에겐 항상 문서화에 대한 고민이 많을 것이다.

개발도 해야하고 테스트도 해야하고 유지보수도 해야하고 할일도 많은데 문서화까지 하라니 아무리 그래도 너무 과한 업무라고 생각이 들 때도 있다.

이런 생각을 나만 했던 것은 아닌지 NestJS에서는 기존 Angular 기반의 Compodoc이라는 오픈소스로 아주 쉽게 문서화할 수 있도록 도와주는 패키지가 존재한다.

이로써 귀찮았던 문서화나 가이드 등을 좀 더 쉽게 정리할 수 있을 것이다.

1. 패키지 설치

npm i -D @compodoc/compodoc

2. compodocrc.json 추가

{
    "includes": "./src",
    "includesName": "프로젝트 문서",
    "name": "프로젝트명 API 문서",
    "output": "docs",
    "theme": "material",
    "hideGenerator": true,
    "disableSourceCode": false,
    "disableCoverage": false,
    "disablePrivate": false,
    "disableProtected": false,
    "disableInternal": false,
    "disableLifeCycleHooks": false,
    "language": "ko-KR",
    "additionalEntryPoints": [
      "src/additional-documentation/*.ts"
    ]
  }

기본 설정

• "includes": "./src"
  • 설명: 문서화할 소스 코드의 기본 디렉토리 경로
  • 용도: 이 경로 내의 TypeScript 파일들이 문서화 대상이 된다
  • 예시: "includes": ["./src", "./libs"]로 여러 경로 지정 가능
• "includesName": "프로젝트 문서"
  • 설명: 문서 사이드바에 표시될 소스 코드 섹션의 제목
  • 용도: 문서 탐색 메뉴에서 소스 코드 섹션의 표시 이름 지정
  • 기본값: "Additional documentation"
• "name": "프로젝트명 API 문서"
  • 설명: 문서화 페이지의 주 제목
  • 용도: 브라우저 탭과 문서 헤더에 표시될 프로젝트 이름
  • 기본값: package.json의 name 필드 값
• "output": "docs"
  • 설명: 생성된 문서가 저장될 디렉토리 경로
  • 용도: 문서 파일들의 출력 위치 지정
  • 기본값: "documentation"
• "theme": "material"
  • 설명: 문서 페이지에 적용할 테마
  • 옵션: "gitbook" (기본값), "material", "original", "postmark", "readthedocs", "stripe", "vagrant"
  • 용도: 문서의 시각적 스타일 지정

표시 제어 옵션

• "hideGenerator": true
  • 설명: 문서 하단의 "Generated using compodoc" 메시지 숨김 여부
  • 용도: 문서에서 Compodoc 광고 제거
  • 기본값: false (표시함)
• "disableSourceCode": false
  • 설명: 소스 코드 보기 비활성화 여부
  • 용도: 문서에서 원본 소스 코드 표시를 제거하고 싶을 때 사용
  • 기본값: false (소스 코드 표시)
• "disableCoverage": false
  • 설명: 문서화 커버리지 보고서 비활성화 여부
  • 용도: 클래스, 메서드 등의 문서화 비율 통계를 숨기고 싶을 때
  • 기본값: false (커버리지 표시)
• "disablePrivate": false
  • 설명: private 멤버(변수, 메서드 등) 표시 여부
  • 용도: 내부용 private 멤버를 문서에서 제외하고 싶을 때
  • 기본값: false (private 멤버 표시)
• "disableProtected": false
  • 설명: protected 멤버 표시 여부
  • 용도: protected 접근 제한자를 가진 멤버를 문서에서 제외하고 싶을 때
  • 기본값: false (protected 멤버 표시)
• "disableInternal": false
  • 설명: @internal 태그가 있는 요소 표시 여부
  • 용도: 내부 구현용 요소를 문서에서 제외하고 싶을 때
  • 기본값: false (internal 요소 표시)
• "disableLifeCycleHooks": false
  • 설명: Angular/NestJS 생명주기 훅 메서드 표시 여부
  • 용도: constructor, ngOnInit 등의 생명주기 메서드를 숨기고 싶을 때
  • 기본값: false (생명주기 훅 표시)

국제화 및 추가 문서

• "language": "ko-KR"
  • 설명: 문서의 UI 언어 설정
  • 옵션: "en-US" (기본값), "fr-FR", "es-ES", "pt-BR", "de-DE", "ja-JP", "zh-CN", "ko-KR" 등
  • 용도: 문서 인터페이스를 특정 언어로 표시
• "additionalEntryPoints": ["src/additional-documentation/*.ts"]
  • 설명: 추가 문서화 파일의 경로 패턴
  • 용도: 주석 처리된 TypeScript 파일을 문서에 포함시키는 데 사용
  • 참고: 이 파일들은 실행되지 않고 문서 생성에만 사용됨

추가 유용한 속성 (현재 설정에 없음)

• "tsconfig": "tsconfig.doc.json"
  • 설명: 문서화에 사용할 TypeScript 설정 파일 경로
  • 기본값: "tsconfig.json"
• "customFavicon": "path/to/favicon.ico"
  • 설명: 문서 페이지의 사용자 정의 파비콘
  • 용도: 브라우저 탭에 표시될 아이콘 변경
• "customLogo": "path/to/logo.png"
  • 설명: 문서 내비게이션 바에 표시될 로고 이미지
  • 용도: 브랜딩을 위한 회사/프로젝트 로고 표시
• "gaID": "UA-XXXXX-Y"
  • 설명: Google Analytics ID
  • 용도: 문서 사용량 추적
• "markdown": "path/to/markdown/files"
  • 설명: 추가 마크다운 파일이 있는 디렉토리
  • 용도: 설명서, 튜토리얼 등의 추가 문서 통합
• "serve": true
  • 설명: 문서 생성 후 서버 시작 여부
  • 용도: 문서 생성 후 자동으로 브라우저에서 문서 확인

3. package.json 수정

"scripts": {
        "docs:generate-readmes": "node scripts/generate-module-readmes.mjs",
        "docs:generate": "npm run docs:generate-readmes && compodoc -p tsconfig.json -d docs -s",
        "docs:serve": "compodoc -s -d ./docs"
}

"docs:generate-readmes" 명령어

 

"docs:generate-readmes": "node scripts/generate-module-readmes.mjs"

설명:

이 스크립트는 프로젝트의 모듈 디렉토리를 스캔하여 각 모듈에 대한 README.md 파일을 자동으로 생성한다.

구성요소:

• node: Node.js 런타임을 사용해 JavaScript 파일을 실행한다.
• scripts/generate-module-readmes.mjs: ES 모듈 형식의 README 생성 스크립트 파일이다.

용도:

• 모듈별 문서화 구조 자동 생성
• 모든 모듈에 일관된 형식의 README 템플릿 적용
• 문서화 시작점을 제공하여 개발자가 내용만 채울 수 있도록 함

"docs:generate" 명령어

"docs:generate": "npm run docs:generate-readmes && compodoc -p tsconfig.json -d docs -s"

설명:

이 명령어는 먼저 모듈별 README를 생성한 후, Compodoc을 실행하여 전체 프로젝트 문서를 생성하고 로컬 서버를 시작한다.

구성요소:

• npm run docs:generate-readmes: 앞서 정의한 README 생성 스크립트를 실행한다.
• &&: 첫 명령이 성공적으로 완료된 후 다음 명령을 실행하는 연산자
• compodoc: Compodoc CLI 도구를 실행한다.
• -p tsconfig.json: TypeScript 설정 파일을 지정한다.
• -d docs: 생성된 문서가 저장될 출력 디렉토리를 지정한다.
• -s: 문서 생성 후 로컬 서버를 시작하는 옵션(serve).

용도:

• 모듈별 README와 전체 API 문서를 한 번에 생성
• 문서 생성 직후 브라우저에서 즉시 확인 가능
• CI/CD 파이프라인에서 문서 자동 생성 및 배포를 위한 기반

"docs:serve" 명령어

"docs:serve": "compodoc -s -d ./docs"

설명:

이 명령어는 이미 생성된 문서를 위한 로컬 서버를 시작한다. 문서를 새로 생성하지 않고 기존 문서를 확인할 때 사용된다.

구성요소:

• compodoc: Compodoc CLI 도구를 실행한다.
• -s: 서버 모드를 활성화한다.
• -d ./docs: 서빙할 문서 파일이 있는 디렉토리를 지정한다.

용도:

• 이미 생성된 문서를 빠르게 확인
• 문서 내용을 수동으로 편집한 후 결과 확인
• 로컬에서 문서를 검토할 때 사용

위의 모든 명령어를 넣지 않아도, docs:generate 명령어 만으로 문서를 생성하거나 서버를 실행할 수 있다.

4. tsconfig.json 수정

{
  "compilerOptions": {
    ...기존 옵션들,
    "allowJs": true,
  },
  "include": [
    "src/**/*",
    "scripts/**/*.js",
    "scripts/**/*.mjs"
  ]
}

"allowJs": true

설명:

이 옵션은 TypeScript 컴파일러가 JavaScript 파일(.js)을 처리할 수 있도록 허용합니다.

기능:

• JavaScript 파일을 TypeScript 프로젝트에 포함시킬 수 있다.
• JavaScript 파일에 대한 타입 검사를 수행할 수 있다.
• JavaScript 파일을 TypeScript 컴파일 프로세스의 일부로 처리한다.

사용 이점:

• 점진적으로 JavaScript에서 TypeScript로 마이그레이션할 수 있다.
• 서드파티 JavaScript 라이브러리를 직접 포함할 수 있다.
• TypeScript와 JavaScript 파일을 같은 프로젝트에서 혼합해서 사용할 수 있다.

"include": ["src/**/*", "scripts/**/*.js", "scripts/**/*.mjs"]

설명:

이 설정은 TypeScript 컴파일러가 처리할 파일의 경로 패턴을 지정합니다.

패턴별 설명:

"src/**/*"

• src 디렉토리 내의 모든 파일과 하위 디렉토리를 포함한다.
• 이는 프로젝트의 주요 소스 코드 파일을 대상으로 한다.
• 모든 확장자(*.ts, *.tsx, *.js, *.jsx 등)의 파일이 포함된다(allowJs가 true일 경우).

"scripts/**/*.js"

• scripts 디렉토리 내의 모든 JavaScript 파일(*.js)과 하위 디렉토리를 포함한다.
• 빌드, 배포, 유틸리티 등의 스크립트 파일을 대상으로 한다.

"scripts/**/*.mjs"

• scripts 디렉토리 내의 모든 ES 모듈 JavaScript 파일(*.mjs)과 하위 디렉토리를 포함한다.
• ES 모듈 형식으로 작성된 스크립트를 대상으로 한다.
• 특히 generate-module-readmes.mjs 같은 문서 생성 스크립트가 이 패턴에 해당한다.

5. 코파일럿에게 Compodoc 문서화 스타일 요청하기

README.md가 아닌 Compodoc 서버 문서화에 작성될 주석들을 코파일럿에게 요청하면 아주 깔끔하게 정리하여 준다.

사실 문서화의 가장 큰 문제점이 이러한 부분들을 작성하여 유지보수해야 한다는 점인데, 이젠 AI를 이용하여 아주 빠르고 간편하게 작성할 수 있다.

물론 다만 해당 기능에 대한 올바른 설명인지 검수를 꼭 진행하여야 한다.

6. 코파일럿에게 README.md 파일 수정 요청하기

README.md로 만들어질 문서 또한 코파일럿에게 요청하여 작성할 수 있다.

아주 기깔나게 README.md를 만들어주는 것을 볼 수 있다.

7. Compodoc 서버 실행 및 결과 확인

현재는 로컬서버로 실행되도록 하였으므로,

npm run docs:generate 으로 실행한 후 

localhost:8080 으로 접속하면 위 사진들과 같이 문서화가 된 것을 볼 수 있다.

정말이지 오픈소스라고 믿기지 않을만큼 깔끔하게 문서화가 된 것을 볼 수 있다.