리오집사의 기억저장소

ESDoc 설치 및 사용방법 | ES6 자바스크립트 문서화하기

개발/ES6, Typescript
2020. 4. 27. 14:57

목차

     

esdoc은 JavaScript용 문서 제네레이터, 특히 es6에 특화된 documentation generator입니다. 비슷하게 JavaScript의 주석을 문서로 만들어주는 것으로, JSdoc 도 있습니다. 현재 진행하고 있는 프로젝트는 es6로 개발하고 있으므로, esdoc을 설치 및 사용하여 자바스크립트 파일을 주석으로 문서화해보려고 합니다. (JSDOC 설치 관련해서는 다음의 포스팅을 참고해주세요.)

 

JSDoc 설치 및 사용방법 | JavaDoc과 비슷한 JSDoc으로 자바스크립트 문서화

목차 JavaScript에서 JAVADOC 처럼 문서를 뽑아주는 JSDOC 이라는 플러그인이 있습니다. 이에 대해 구체적인 사용방법이 정리되어 있는 블로그가 없는 것 같아 정리해 봅니다. ESDOC 설치 관련해서는 다

pliss.tistory.com

 

적용하려는 프로젝트는 다음과 같이 구성되어 있습니다.

  • Webpack
  • Javascript (es6)

 

 

Step1. esdoc 설치

설치는 간단합니다. 공식 문서에도 잘 나와 있습니다. 아래는 간단히 번역한 것입니다.

# project directory 로 이동하세요
cd your-project/

# ESDOC 과 표준 플러그인을 설치하세요.
npm install esdoc esdoc-standard-plugin

# 다음과 같이 configuration 파일을 작성하세요.
echo '{
  "source": "./src",
  "destination": "./docs",
  "plugins": [{"name": "esdoc-standard-plugin"}]
}' > .esdoc.json

# run ESDoc
./node_modules/.bin/esdoc

# 문서를 확인해 보세요.
open ./docs/index.html

 

다음과 같이 적용된 모습이 나오면 됩니다.

ESDOC 화면
ESDOC 화면

 

 

Step2. 테마 적용

esdoc은 아직까지는 jsdoc 처럼 테마가 많지 않은 것 같습니다. 저는 esdoc-custom-theme 의 Light mode를 적용하려 합니다.

Light mode 테마

Light mode 테마
Light mode 테마

적용 방법

# project directory 로 이동하세요
cd your-project/

# ESDOC 과 표준 플러그인을 설치하세요. (esdoc)은 Step1을 하지 않았을 때 입력하세요.
npm install (esdoc) esdoc-publish-html-plugin esdoc-custom-theme -D --save

# 다음과 같이 configuration 파일을 작성하세요.
# Step1와 비교해보면, plugins 가 바뀌었습니다.
echo '{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {
      "name": "esdoc-publish-html-plugin",
      "option": {
        "template": "./node_modules/esdoc-custom-theme/template"
      }
    }
  ]
}' > .esdoc.json

# run ESDoc
./node_modules/.bin/esdoc

# 문서를 확인해 보세요.
open ./docs/index.html

 

다음과 같이 비슷한 형태로 나온다면, 테마가 정상적으로 적용된 겁니다.

Light mode 테마 적용 화면
Light mode 테마 적용 화면

 

Step3. 커스터마이징

이제 저희 프로젝트에 맞게 다음을 진행해보려고 합니다.

  • 문서 저작권 및 Repository 연결
  • 마크다운으로 좀 더 상세한 문서 작성
  • 테마 수정

 

추가 플러그인 설치

커스터마이징을 위해서 먼저 다음의 플러그인을 설치합니다.

# project directory 로 이동하세요
cd your-project/

# 커스터마이징을 위한 추가 플러그인을 설치합니다
npm install esdoc-brand-plugin esdoc-inject-style-plugin esdoc-standard-plugin -D --save

 

Configuration 파일 수정

아래를 따라하면,

  • esdoc-brand-plugin 에서 자신의 git 주소와 문서 타이틀 등을 수정할 수 있습니다.
  • esdoc-inject-style-plugin 에서 문서의 스타일(테마)를 수정할 수 있습니다.
    • 추가로 cofiguration 파일에 명시된 custom-styles.css 를 생성해야 동작합니다
  • esdoc-standard-plugin 에서 마크다운 문서를 추가할 수 있습니다.
    • 추가로 cofiguration 파일에 명시된 마크다운 문서를 생성해야 동작합니다
# project directory 로 이동하세요
cd your-project/

# vi 편집기로 Step1,Step2에서 수정했던 .esdoc.json 파일을 열어, plugin 쪽을 다시 한 번 수정합니다.

{
  "plugins": [
    {
      "name": "esdoc-brand-plugin",
      "option": {
        "title": "esdoc-custom-theme",
        "description": "A customizable theme for esdoc",
        "repository": "https://github.com/sinnerschrader/esdoc-custom-theme",
        "site": "sinnerschrader.github.io/esdoc-custom-theme",
        "author": "https://github.com/pixelass"
      }
    },
    {
      "name": "esdoc-inject-style-plugin",
      "option": {
      "enable": true,
        "styles": [
          "./custom-styles.css"
        ]
      }
    },
    {
      "name": "esdoc-publish-html-plugin",
      "option": {
        "template": "./node_modules/esdoc-custom-theme/template"
      }
    },
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "coverage": {
          "enable": true
        },
        "accessor": {
          "access": ["public"],
          "autoPrivate": true
        },
        "manual": {
          "index": "./manual/index.md",
          "globalIndex": true,
          "asset": "./manual/assets",
          "files": [
            "./manual/installation.md"
            "./manual/usage.md"
          ]
        }
      }
    }
  ]
}

 

custom-styles.css 파일 수정

위의 configuration 파일에서 esdoc 문서의 테마 커스텀을 위해,

"name": "esdoc-inject-style-plugin",
      "option": {
      "enable": true,
        "styles": [
          "./custom-styles.css"
        ]
      }

와 같이 수정했기 때문에, 현재는 존재하지 않는 custom-styels.css 파일을 만들어줘야 합니다.

 

# project directory 로 이동하세요
cd your-project/

# vi 편집기로 custom-styles.css 파일을 생성합니다.
vi custom-styles.css

# 해당 파일에 다음을 기입합니다.
:root.light {
  --main-background: #fff;
  --main-color: #000;
  --main-border-color: #c9d0d5;
  --main-link-color: #3300d1;
  --main-focus-color: #7588fb;

  --main-header-background: #3300d1;
  --main-header-color: #fff;
  --main-header-border-color: #010049;
  --main-header-link-hover-shade: rgba(255, 255, 255, 0.1);
  --main-header-link-active-shade: rgba(255, 255, 255, 0.2);
  --main-header-shadow: 0 0.175rem 0.25rem rgba(0, 0, 0, 0.35), 0 0.25rem 0.5rem rgba(0, 0, 0, 0.65);

  --left-sidebar-background: #f2f5f9;
  --left-sidebar-background-active: #acb4b7;
  --left-sidebar-color-active: #000;
  --left-sidebar-color: #000;
  --left-sidebar-border-color: #c9d0d5;
  --left-sidebar-indent-background: none;
  --left-sidebar-shadow: none;

  --right-sidebar-background: #212429;
  --right-sidebar-background-active: #16181f;
  --right-sidebar-color-active: #fff;
  --right-sidebar-color: #fff;
  --right-sidebar-border-color: #2d3038;
  --right-sidebar-indent-background: none;
  --right-sidebar-shadow: -0.125rem 0 0.25rem rgba(0, 0, 0, 0.25), -0.175rem 0 0.35rem rgba(0, 0, 0, 0.45);

  --card-link-hover-shade: rgba(0, 0, 0, 0.1);

  --search-separator-background: #3300d1;
  --search-separator-color: #fff;
  --search-result-background: #f2f5f9;
  --search-result-color: #000;
  --search-result-border-color: #c9d0d5;
  --search-result-selected-background: #c9d0d5;
  --search-result-selected-color: #000;
  --search-result-shadow: 0 0.25rem 0.25rem rgba(0, 0, 0, 0.35), 0 0.5rem 0.5rem rgba(0, 0, 0, 0.65);
  --search-result-hover-shade: rgba(0, 0, 0, 0.1);
  --search-result-focus-color: #7588fb;

  --main-code-background: #c9d0d5;
  --main-code-color: #0d6663;
  --main-code-border-color: #c9d0d5;

  --pretty-code-error-background: #7f012a;
  --pretty-code-error-color: #fff;

  --kind-background: #16181f;
  --kind-color: #696e76;

  --kind-function-background: hsl(0, 80%, 70%);
  --kind-function-color: hsl(0, 90%, 20%);

  --kind-class-background: hsl(30, 80%, 70%);
  --kind-class-color: hsl(30, 90%, 20%);

  --kind-variable-background: hsl(60, 80%, 70%);
  --kind-variable-color: hsl(60, 90%, 20%);

  --table-color: #000;
  --table-background: #f2f5f9;
  --table-border-color: #c9d0d5;
  --td-color: #000;
  --td-background: #f2f5f9;
  --td-border-color: #c9d0d5;
  --thead-color: #000;
  --thead-background: #acb4b7;
  --thead-border-color: #c9d0d5;

  --light-switch-color: #fff;
  --light-switch-background: #212429;
}

 

 

마크다운 파일 생성

위의 configuration 파일에서 esdoc 문서에 코드 외의 추가 마크다운 문서를 작성하기 위해서,

{
     "name": "esdoc-standard-plugin",
     "option": {
       "coverage": {
         "enable": true
       },
       "accessor": {
         "access": ["public"],
         "autoPrivate": true
       },
       "manual": {
         "index": "./manual/index.md",
         "globalIndex": true,
         "asset": "./manual/assets",
         "files": [
           "./manual/installation.md"
           "./manual/usage.md"
         ]
       }
     }

와 같이 수정했기 때문에, 현재는 존재하지 않는 custom-styels.css 파일을 만들어줘야 합니다.

# project directory 로 이동하세요
cd your-project/

# manual 폴더와 manual/assets 폴더를 만듭니다
mkdir manual
mkdir manual/assets

# manual 폴더로 이동합니다
cd manual

# 위에서 기입한 마크다운 문서를 만듭니다.
touch index.md installation.md usage.md

 

최종확인

커스터마이징이 제대로 되었을까요? 확인해 봅시다.

# project directory 로 이동하세요
cd your-project/

# run ESDoc
./node_modules/.bin/esdoc

# 문서를 확인해 보세요.
open ./docs/index.html

저는 다음과 같이 완성했습니다.

반응형
저작자표시 비영리 변경금지

공유하기

facebook twitter kakaoTalk kakaostory naver band

'개발/ES6, Typescript' 의 관련글

티스토리툴바