JSDoc 페이지를 GitHub Page로 배포하기

JSDoc

JSDoc's purpose is to document the API of your JavaScript application or library.
- Use JSDoc

JSDoc은 Javascript의 API Document를 간단하게 만들어주는 라이브러리이다.

 

JSDoc 설치 및 사용 방법

JSDoc은 전역으로(globally) 설치해야한다. (경우에 따라서는 sudo가 필요할 수도 있다)

npm i -g jsdoc

사용방법은 간단하다. 적용하기 원하는 변수나 함수 등 위에 /** */스타일의 주석을 작성하면 된다.

/** This is a description of the foo function. */
function foo() {
}

공식 문서에 자세한 사용법이 작성되어 있다.

https://jsdoc.app/

Use JSDoc: Index

 

JSDoc Publish 방법

터미널에 다음과 같이 입력하여 index.js의 JSDoc을 퍼블리시할 수 있다.

jsdoc src/index.js

뒤에 README.md를 추가하면 JSDoc의 Home에 README 페이지를 추가할 수 있다.

 

jsdoc src/index.js README.md

 

JSDoc을 GitHub Page에 배포하기

GitHub Page로 배포하는 것은 생각보다 간단하다.위의 방법을 통해 발행했다면 out이라는 폴더에 빌드된 파일이 들어있을 것이다.

 

해당 폴더의 이름을 docs로 바꾼다.

 

그후 깃허브 레포지토리 설정의 Pages에서 다음과 같이 설정한다.

 

 

그러면 자동으로 저장되고 잠시만 기다리면...

 

짜잔! 깃허브 페이지에 배포가 완료되었다.

 

배포가 완료된 JSDoc Page

간단한 과정에 비해 너무 예쁘고 깔끔하다!

 

 

추가 팁!

다음과 같이 configuration file을 추가하면 (이름은 자유!) JSDoc을 발행할 때 폴더 이름을 바꿀 수 있다!

// jsdoc-conf.json

{
  "opts": {
    "destination": "./docs/"
  }
}

이후 터미널 명령어 뒤에 -c jsdoc-conf.json 를 추가한다.

jsdoc src/index.js -c jsdoc-conf.json

물론 훠어얼씬 더 많은 설정을 제공한다!

https://jsdoc.app/about-configuring-jsdoc.html

Use JSDoc: Configuring JSDoc with a configuration file