[TypeDoc] TypeDoc으로 TypeScript 프로젝트 문서화 하기

Intro

프로젝트를 진행하면서 jsdoc을 활용해서 코드 주석을 작성하고 있었다. 문서화를 위해 문서 생성을 시도했지만 타입스크립트 변환이 일부 실패하면서 타입스크립트 문서화에 적합한 라이브러리를 찾아보던 중 TSDoc 와 TypeDoc 라이브러리를 알게 되었다. 

 

TSDoc

• 공식 사이트 : https://tsdoc.org/
• NPM : https://www.npmjs.com/package/@microsoft/tsdoc
• 깃허브 : https://github.com/microsoft/tsdoc  

• 조사해보니 TSDoc은 Microsoft가 제안하고 주도하는 오픈 소스 표준으로, TypeScript 코드의 주석을 문서화하기 위한 스타일 가이드를 제공한다고 한다. 
• 나는 타입스크립트 기반의 주석을 잘 문서화시킬 수 있는 라이브러리를 찾고 있었는데 TSDoc는 문서화를 시켜주는 기능은 없다고 한다.
• TSDoc 표준에 맞지 않는 주석에 대한 검증 기능을 지원하기 때문에 오류나 경고를 표시를 제공받을 수 있다고 한다.
• TSDoc의 존재를 몰라 jsdoc와 jsdoc-plugin-typescript을 설치하여 타입스크립트를 변환하고 있었는데 이후에 타입스크립트 기반의 프로젝트를 구축할 경우 TSDoc만 설치해서 사용하면 될 것 같다.

 

NPM Trends 통계

3가지 라이브러리들의 npm 다운로드 통계를 보니 2024년부터 TSDoc의 다운로드 수가 JSDoc를 앞지르는 것을 볼 수 있었다.

https://npmtrends.com/@microsoft/tsdoc-vs-jsdoc-vs-typedoc

 

JSDocㆍTSDoc 비교

특징	JSDoc	TSDoc
목적	JavaScript 주석 표준을 제공하여 문서화를 돕는 도구	TypeScript 코드 주석을 위한 표준을 정의하여 문서화 품질을 높임
주요 사용 대상	주로 JavaScript 프로젝트	TypeScript 프로젝트
주석 작성 방식	@param, @return 등 다양한 주석 태그를 제공	JSDoc과 유사한 주석 태그를 제공하지만, TypeScript에 최적화됨
문서 생성 기능	HTML, 마크다운 등으로 문서 생성	자체적으로 문서 생성 기능 없음 (TypeDoc, API Extractor와 함께 사용하여 문서화 가능)
TypeScript 지원	기본적으로 JavaScript를 대상으로 하므로 TypeScript 지원이 제한적	TypeScript용으로 설계되어, TypeScript 프로젝트에 최적화된 주석 표준을 제공
타사 도구와의 호환성	TypeScript 플러그인을 사용해 TypeDoc과 같은 도구에서 제한적으로 사용 가능	TypeDoc, API Extractor 등 TypeScript 기반 도구와의 높은 호환성을 제공
주석 검증 기능	주석 자체에 대한 검증 기능 없음	TSDoc 표준에 맞지 않는 주석에 대한 검증 기능을 제공하여 오류나 경고를 표시할 수 있음
확장성	플러그인을 통해 확장 가능, jsdoc-plugin-typescript 등과 함께 사용	확장성은 제한적이지만 TypeScript에 최적화된 표준을 유지
관리 주체	커뮤니티 기반 오픈 소스	Microsoft에서 주도하는 오픈 소스 프로젝트
주석 태그	@param, @returns, @example 등 다양한 태그 지원	대부분의 JSDoc 태그를 지원하나, TypeScript에 맞게 일부 태그가 조정됨
장점	사용이 간단하며, 다양한 언어 및 프로젝트에서 널리 사용됨	TypeScript에 특화된 표준 제공, 주석 품질 검증 가능
단점	TypeScript에 최적화된 문서화 품질이 제한적임	JSDoc처럼 대중적으로 사용되지 않으며, 추가 도구(TypeDoc 등) 없이는 문서화가 어려움

 

tsdoc.json VS @microsoft/tsdoc - 헷갈림 주의

TSDoc 공식 홈페이지

 

처음에 TSDoc 공식 사이트 방문 후 npm에서도 검색 해봤다. npm 사이트에서 tsdoc 단어를 입력 후 별 생각 없이 가장 상단에 있는 라이브러리를 클릭했는데 Weekly Downloads가 2명, Last publish가 4달 전이었다.

npm 사이트

Weekly Downloads가 2명, Last publish가 4달 전

 

이상함을 감지하고 공식 사이트를 다시 봤더니 패키지명이 @microsoft/tsdoc 이었다.

 

다시 NPM에서 확인해보니 Weekly Downloads가 2,914,757명인 것을 확인할 수 있었다.

 

TypeDoc으로 프로젝트 문서화하기

• 공식 사이트 : https://typedoc.org/
• NPM : https://www.npmjs.com/package/typedoc
• 깃허브 : https://github.com/TypeStrong/typedoc  

 

TypeDoc 설치하기

npm i typedoc

 

typedoc.json

프로젝트의 최상위 경로에 typedoc.json 파일을 추가 후 아래와 같이 작성한다.

// typedoc.json

{
  "entryPoints": ["src"],
  "entryPointStrategy": "expand",
  "out": "docs",
  "cleanOutputDir": true,
  "readme": "none",
  "tsconfig": "./tsconfig.json",
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeExternals": false,
  "includeVersion": true,
  "disableSources": false,
  "categorizeByGroup": true,
  "searchInComments": false,
  "skipErrorChecking": true
}

• entryPoints: ["src"]
  • 문서화를 시작할 파일 또는 디렉토리의 경로를 설정한다. src 디렉토리의 모든 파일이 문서화 대상으로 지정하기 위해 "src"라고 입력했지만 보통은 "src/index.ts"으로 많이 설정하는 것 같다.
• entryPointStrategy: "expand"
  • 엔트리 포인트를 처리하는 방식을 지정한다.
    • "expand"는 지정된 엔트리 포인트가 디렉토리일 경우, 해당 디렉토리의 모든 파일을 문서화 대상에 포함시킨다.
• out: "docs"
  • 문서화 파일이 출력될 디렉토리 경로를 설정한다. 여기서는 docs 디렉토리에 문서가 생성된다.
• cleanOutputDir: true
  • 출력 디렉토리 초기화 여부를 지정한다.
  • true일 경우, 문서 생성 전에 지정된 출력 폴더(out 경로)를 비워 새로운 문서를 생성한다.
• readme: "none"
  • 문서화된 페이지에 README 파일을 포함할지 여부를 결정한다.
    • "none"은 README 파일을 포함하지 않음을 의미한다.
• tsconfig: "./tsconfig.json"
  • TypeScript 설정 파일 경로를 지정한다. TypeDoc은 이 파일의 설정을 참고하여 TypeScript 구성을 기반으로 문서를 생성한다.
• excludePrivate: true
  • private로 선언된 멤버들을 문서화에서 제외할지 여부를 설정한다.
  • true일 경우 private 멤버는 문서화되지 않는다.
• excludeProtected: true
  • protected로 선언된 멤버들을 문서화에서 제외할지 여부를 설정한다.
  • true일 경우 protected 멤버는 문서화되지 않는다.
• excludeExternals: false
  • 외부 모듈을 문서화에서 제외할지 여부를 설정한다.
  • false일 경우, 외부 모듈도 문서화에 포함된다.
• includeVersion: true
  • 프로젝트의 버전을 문서에 포함할지 여부를 설정한다.
  • true일 경우, package.json의 version 필드 값이 문서에 추가된다.
• disableSources: false
  • 소스 코드 링크를 생성할지 여부를 설정한다.
  • false일 경우, 각 문서화된 요소에 소스 코드 링크가 포함된다.
• categorizeByGroup: true
  • 문서를 그룹별로 나눌지 여부를 설정한다.
  • true일 경우, 문서가 그룹별로 분류되어 가독성을 높여준다.
• searchInComments: false
  • 주석 내용도 검색 대상에 포함할지 여부를 결정한다.
  • false일 경우, 검색은 주석이 아닌 문서화된 코드만 대상으로 한다.
• skipErrorChecking: true
  • 타입 검사 오류 무시 여부를 설정한다.
  • true일 경우, 타입 검사 오류를 무시하고 문서를 생성한다.

 

tsconfig.json 파일 설정

최상위 경로의 tsconfig.json 파일에 typedocOptions 옵션을 추가한다.

// tsconfig.json

{
	"compilerOptions": {
    ...
	},
    "path": {
        ...
    },
    "typedocOptions": {
        "entryPoints": ["src"],
        "out": "docs"
    }
}

 

packaget.json

package.json의 scripts에 추가하고 싶은 명령어를 typedoc 실행 명령어를 추가할 수 있다. 명령어는 “docs”, “typedoc”등 임의로 설정할 수 있다.

// packaget.json

{
    "scripts": {
        ...
        "docs": "typedoc --options typedoc.json"
    }
}

 

docs 문서 생성하기

package.json에 script를 추가 후 터미널 창에서 명령어를 입력하면 명령어가 실행 되면서 최상위 경로에 docs 폴더가 생성된다.

npm run docs

docs 폴더가 생성된 것을 확인할 수 있다.

index.html 파일을 열면 브라우저에서 문서를 확인할 수 있다.