JSDoc에서 템플릿을 사용해 보도록 합시다

📌 연관 글

1. Javascript Documentation 라이브러리 JSDoc를 사용해 봅시다
2. JSDoc을 설정 파일로 빼서 사용해보도록 합시다
3. JSDoc에서 템플릿을 사용해 보도록 합시다
4. Webpack과 JSDoc을 연동하여 자동화를 시켜봅시다

---

우리는 기본적인 JSDoc 설정을 끝내고 JSDoc을 이용하여 Documentation까지 만들었습니다.

이렇듯 쉽게 Documentation을 만들수 있고 웹 기반으로 볼 수 있다는 장점은 저희에게 큰 메리트를 줍니다.

하지만 JSDoc이 자동으로 Documentation을 Styling을 해줘서 딱히 특색이 있어 보이진 않습니다.

이러한 사용자의 Needs를 JSDoc 또한 알고 있었을까요?

JSDoc에서 템플릿을 지원하고 있습니다.

같이 한번 적용해 보도록 할까요?

 

---

JSDoc 템플릿 Better-docs

JSDoc 기본 템플릿

저희가 만든 JSDoc Documentation입니다. 

깔끔 바로 그 자체네요.

하지만 이러한 스타일은 깔끔하긴 하지만 큰 특색이 있어 보이지 않습니다.

그래서 제가 가장 좋아하고 React를 사용할 때 주로 사용하는 Better-docs라는 템플릿을 적용하도록 하겠습니다.

어려워 보인다구요??

그렇게 무서워하지 마세요 생각보다 간단함에 놀라실겁니다.😀

 

Better-docs 템플릿

 

Better-docs 템플릿 적용해보기

자 그럼 먼저 npm에서 better-docs를 다운로드해 보겠습니다.

먼저 터미널에 아래와 같이 입력해보도록 하겠습니다.

$ npm install --save-dev better-docs

그럼 아래 사진과 같이 Better-docs가 다운로드 된 것을 알 수 있습니다.

그 후 저희가 이전 포스팅에서 생성한 jsdoc.config.js를 열어보도록하겠습니다.

그런 다음 아래와 같이 입력해보도록 하겠습니다.

{
  "plugins": ["node_modules/jsdoc/plugins/markdown"], // Markdown을 사용하기 위해 플러그인을 추가합니다.
  "recurseDepth": 10, // -r 명령 행 플래그로 재귀가 사용 가능한 경우 JSDoc은 10 레벨 깊이의 파일을 검색합니다.
  "source": {
    "include": ["./"], // ./ 이하 js, jsx, jsdoc을 대상으로 합니다.
    "includePattern": ".+\\.js(x|doc)?$", // js, jsx, jsdoc 이라는 확장자를 가진 것을 Docs로 변환합니다.
    "excludePattern": "(^|\\/|\\\\)_" // 밑줄로 시작하거나 밑줄로 시작하는 디렉토리에있는 모든 파일은 무시됩니다.
  },
  "sourceType": "module", // ES 2015를 지원하기 위해 적용
  "tags": {
    "allowUnknownTags": true // JSDoc이 알 수 없는 태그를 지원하도록 설정
  },
  "opts": {
    "encoding": "utf8", // Docs에서 한글을 사용할 수 있도록 설정
    "destination": "./docs", // 기존에 생성되던 out이라는 폴더를 docs라는 폴더로 생성
    "readme": "README.md", // README.md를 추가
    "template": "node_modules/better-docs"
  }
}

자 무엇이 바뀌었을까요?

그렇습니다.

opts에 template를 추가하여 Better-docs를 넣어주었습니다.

그럼 Documentation을 빌드해 볼까요? 

해당 프로젝트 루트 터미널에 접속하여 아래와 같이 입력해 주세요

$ ./node_modules/.bin/jsdoc -c .\jsdoc.config.json .

그럼 아래와 같이 템플릿이 적용된 것을 알 수 있습니다.

어때요 생각보다 간단하죠?

마치며

이것으로 저희는 JSDoc 템플릿을 적용해 보았습니다.

어떤가요? 꽤 할만하지 않나요?

참고로 각 템플릿 마다 지원하는 기능이 다르므로,

JSDoc 링크를 참고하여 각 템플릿에 지원되는 기능들을 확인후 선택하는 것을 추천드립니다.

그럼 다음에 뵙겠습니다.😘