Webpack과 JSDoc을 연동하여 자동화를 시켜봅시다

📌 연관 글

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

---

이제 이 JSDoc에 마지막 시리즈 입니다.

기존에 저희는 JSDoc을 사용하기 위해서 커맨드를 입력해 Documentation을 생성했습니다.

하지만 이러한 작업은 개발자의 업무 효율의 지장을 주고, 귀찮은 작업일 수 밖에 없습니다.

하지만 이러한 문제를 해결할 수 있는 방법이 있습니다.

지금 바로 알아보도록 하시죠

 

Webpack + JSDoc = 자동화?

많은 Frontend 개발자들은 Webpack 혹은 Parcel 같은

모듈 번들러를 통해 Web Application을 모듈화 하여 사용하고 있습니다.

저 또한 React.js를 사용하면서 자연스럽게 Webpack을 자주 사용하게 되었는데,

Documentation관리를 위해 JSDoc과 같이 사용할 때 종종 JSDoc 컴파일 명령어를 사용하지 않아

Documentation이 최신버전을 유지하지 않는 현상이 발생하는일이 종종 있었습니다.

이러한 이슈를 해결하기 위해 방법을 찾아봤고 이와 같은 패키지를 찾게 되었습니다.

 

Webpack과 jsdoc-webpack-plugin 설치하기

사진을 클릭하면 해당 사이트로 이동할 수 있습니다.

해당 패키지는 Webpack 빌드 시 JSDoc과 함꼐 빌드를 도와주는 NPM 패키지 입니다.

자 백문이 불여일견이라 했나요?

한번 직접 경험해 보도록 하겠습니다.

먼저 저희는 그동안 Webpack을 사용하지 않았습니다.

그러므로 Webpack과 같이 해당 패키지를 설치해 보겠습니다.

 

$ npm i -D webpack webpack-cli jsdoc-webpack-plugin

 

그 후 webpack.config.js라는 파일을 만들도록 합니다.

 

webpack.config.js 생성

위와 같은 환경이 설정되었습니다.

자 기본적인 설치를 완료 하였습니다.

하지만 이렇게 만들었다고 JSDoc 자동화가 되지 않습니다.

다음 Webpack에서 JSDoc이 실행이 될 수 있도록 설정해 보도록 하겠습니다.

 

Webpack에 JSDoc 끼얹기

저희가 이 포스팅을 보는 주 된 목적이 뭐였죠?

그렇습니다. Webpack에 JSDoc을 끼얹어 자동화를 만들기 위해 이 포스팅을 보는거 였습니다.

(Webpack에 대한 자세한 설명은 추후 Webpack 포스팅에서 다루도록 하겠습니다.)

Webpack에 JSDoc을 추가하는 것은 간단합니다.

우리가 위에서 만들었던 webpakck.config.js에 아래와 같이 입력합니다.

const path = require("path");
const JsDocPlugin = require("jsdoc-webpack-plugin"); // jsdoc-webpack-plugin을 불러옵니다.

module.exports = {
  entry: "./index.js",
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "main.js"
  },
  plugins: [
    new JsDocPlugin({
      // 이 부분이 핵심
      conf: "jsdoc.config.json", // config 이름 추가
      cwd: ".", // config의 경로
      preserveTmpFile: false // 임시 파일을 보존할 지 설정
    })
  ]
};

핵심적으로 알아야 할 내용은 주석으로 달아놓았습니다.

그 후 package.json에 들어가 script에 아래와 같이 입력합니다.

 

{
  ...
  "scripts": {
    "start": "webpack"
    ...
  },
  ...
}

script에 start 구문을 추가한 모습

 

자 그 후 루트 터미널에서 아래와 같이 커맨드를 입력합니다.

 

$ npm run start

 

그럼 아래사진과 같이 webpack 과 JSDoc이 같이 빌드 되면서

동작하는 것을 확인할 수 있습니다.

 

Webpack과 JSDoc이 같이 동작하는 모습

하지만 아래와 같이 

 

SyntaxError: D:\project\jsdocs-test\jsdoc.config.json: Unexpected token / in JSON at position

 

같은 에러가 발생할 경우 jsdoc.config.json 파일에 주석이 문제일 수 있으므로 모든 주석을 다 지워준 후 

webpack을 빌드해 주면 정상적으로 JSDoc이 동작하는 것을 확인할 수 있습니다.

 

jsdoc.config.json 파일에서 에러 발생

마치며

자 이것으로 저희는 JSDoc을 자동화하여 간단히 Documentation을 만들수 있게 되었습니다.

어떠신가요? 생각보다 간단하지 않나요?

이제 JSDoc 시리즈 4개를 다 마무리하였고, 추후 계발을 진행하면서 JSDoc을 사용하는데

도움을 줄 만한 내용이 있으면 추가 포스팅 하도록 하겠습니다.