당신의 자바스크립트 API 문서는 안녕하신가요?

이 글을 읽고 있을 개발자라면 적어도 한 번쯤 API 문서를 작성해 본 경험이 있으리라 생각한다. "오전까지 100개 함수에 대한 API 문서를 만들어주세요."라는 업무가 주어졌다고 가정해보자. 이때 어떤 그림이 그려지는가? 워드 또는 엑셀을 실행하고, 테이블을 추가하고, 소스 코드를 들여다보며 열심히 API 정보를 입력하고 있는 모습이 떠올랐는가? 문서화 도구를 사용해 보았고 문서화 도구가 주는 이점을 잘 알고 있는 이들이라면, 이런 상상은 절대 하고 싶지 않을 것이다.

여기서 말하는 문서화 도구는 무엇일까? 문서화 도구(Documentation Generator)란, 소스 파일에 작성된 주석을 파싱하여 클래스, 메서드 등 API 정보를 HTML 문서로 생성해주는 도구를 지칭한다. 개발 중인 코드에 주석이 잘 작성되어 있다면, 문서화 도구가 제공하는 명령어 한 줄만으로 불필요한 핸드메이드 작업 을 피할 수 있다. 자바의 Javadoc, 파이썬의 Sphinx 등이 문서화 도구에 해당한다. 당연히 자바스크립트를 위한 문서화 도구도 존재한다. 잘 알려진 자바스크립트 문서화 도구로는 JSDoc이 있다.

NHN FE개발랩에서는 이러한 문서화 도구를 적극적으로 사용해 왔다. JSDoc 기본 템플릿을 커스터마이징 한 TOAST UI JSDoc Template를 개발하기도 했으며, 이 모듈을 사용해 TOAST UI 제품의 API 문서를 만들었다. 그리고 최근에는 새 문서화 도구인 TOAST UI Doc을 출시하게 되었다. TOAST UI Doc은 기존의 TOAST UI JSDoc Template와 닮은 듯 보이지만, 개발 및 관리 관점에서 더 나은 자바스크립트 문서화 도구를 만들기 위한 목적으로 시작된 프로젝트다. 이 글에서는 개발부터 출시되기까지의 과정, 사용된 기술, 사용 이점 등 TOAST UI Doc에 대한 전반적인 이야기를 다뤄보려고 한다. TOAST UI Doc이 자바스크립트 문서화 도구의 하나로 잘 자리 잡길 바라는 마음과 함께 이 글을 시작해보겠다.

TOAST UI Doc 출시 과정

TOAST UI Doc이 출시되기 전까지, TOAST UI의 제품들은 API 문서를 생성할 때 TOAST UI JSDoc Template(이하 JSDoc Template)를 사용했었다. 아래 이미지는 API 문서가 생성되는 과정을 그려본 것이다.

JSDoc Template는 문서화 도구가 아니라 JSDoc 문서 템플릿 이다. JSDoc은 자바스크립트에서 주석을 파싱하고, 파싱된 데이터에 템플릿을 입혀 HTML 파일을 생성한다. JSDoc 설정 파일에서 템플릿으로 tui-jsdoc-template을 지정하면, 기본 템플릿 대신 TOAST UI에서 개발한 템플릿을 사용하게 된다. JSDoc Template 데모 페이지에서 본 LNB(탭, 검색, 토글 메뉴 등), Examples 페이지 등은 JSDoc을 확장해 만든 추가 기능들이다.

JSDoc Template는 기본 템플릿보다 다양한 기능을 제공한다는 점에서 좋은 반응을 얻었지만(JSDoc 깃헙 리드미에 링크되기도 했다), 가독성이 떨어져서 API를 보기 힘들다 는 의견이 종종 제보되었다. 우리는 이 문제를 해결하기 위해 JSDoc Template의 디자인을 개선하기로 했다.

이대로 사용해도 괜찮을까?

디자인 개선 작업을 진행하기 전, JSDoc Template를 살펴보았고 몇 가지 문제점들이 보였다. JSDoc 기본 템플릿을 확장한 형태다 보니 JSDoc 모듈 의존 코드가 많고 복잡했다. 그래서 기능을 추가하거나 변경할 때 JSDoc 동작 원리와 구조를 이해하기 위한 학습 비용이 컸다. 또한 JSDoc에서 Taffy 타입의 파싱 데이터 처리, 템플릿 파일(*.tmpl)을 사용하는 구조는 JSDoc Template의 유지보수를 어렵게 만들었다.

결국 디자인보다 관리 이슈부터 먼저 해결해야 했고, 이 시점에 JSDoc의 대안이 될 수 있는 다른 도구들도 찾아보게 되었다. 자바스크립트 문서화 도구의 종류는 생각보다 꽤 많았다. 아래 이미지는 자바스크립트 문서화 도구의 인기 순위를 비교한 것이다. (2018년 7월 기준 비교)

부동의 1위는 JSDoc이였다. 이 랭킹 목록에서 JSDoc을 제외한 다른 도구들을 검토해보았지만, 다음 3가지 조건을 모두 만족하는 도구는 거의 없었다.

1. JSDoc 주석을 파싱할 수 있어야 한다.
2. 템플릿을 제공하며 확장 가능해야 한다.
3. 6개월 이내 커밋 활동이 있어야 한다.

YUIDoc, ESDoc 정도였지만 이 도구들마저도 JSDoc 등장과 함께 유명세를 잃어버린 것들이었다. 이때 새로운 도구가 눈에 들어왔다. npm 다운로드 수치를 비교한 지표를 살펴보던 중, documentation.js를 발견하게 되었다.

documentation.js의 발견

documentation.js는 우리가 찾고 있는 모든 조건을 만족했다. documentation.js에서 눈에 띄는 기능들은 다음과 같았다.

• ES5, ES2017, JSX, Vue, Flow 타입을 지원한다.
• JSDoc 파싱 데이터를 마크다운, JSON으로 제공한다.
• 노드 환경에서 사용할 수 있는 사용자 API를 제공한다.

기능 면에서 충분히 사용해 볼 가치가 있었다. 마지막 검토 사항으로, 템플릿을 어떤 방식으로 확장할지 테스트해 보았다. documentation.js의 기본 템플릿은 UI가 JSDoc Template와 유사한 형태로 구성되어 있어, 변경된 디자인을 적용하기에 쉬워 보였다. 하지만 검색, Examples 페이지 같은 추가 기능들은 documentation.js 템플릿에 맞춰 다시 개발을 해야 했다. 결국 JSDoc Template를 처음 만들 때와 같은 작업을 하는 셈이었다. 선택의 갈림길에 섰다. 이미 다 만들어져 있는 기능들이니 JSDoc Template를 디자인만 업데이트해서 쓸 것인가 아니면 공수가 들더라도 documentation.js를 사용해 다시 잘 만들어볼 것인가?

랩퍼를 만들어보는건 어떨까?

후자로 의견이 기울었지만 단순히 템플릿에 기능만 추가한다고 해서 기존에 JSDoc Template가 가지고 있던 문제가 해결될 것 같지는 않았다. documentation.js에서는 템플릿으로 핸들바를 사용하는데 템플릿을 확장한다고 할 때 JSDoc Template 처럼 코드도 복잡해지고 필요한 데이터를 가공하는 방법에도 제약이 많았다. 대신 우리는 위에서 소개한 documentation.js의 기능 중, JSDoc 파싱 데이터를 JSON으로 제공한다는 점에 주목했다. 파싱 데이터만 있다면, 다른 도구의 템플릿을 확장하는 방식을 사용하는 대신 독자적인 문서화 도구를 만들 수 있기 때문이다.

직접 템플릿을 만들고 문서를 생성할 수 있는 방법을 찾았다. 이때 정적 사이트 생성기(Static Site Generator) 가 떠올랐다. 정적 사이트는 정적 웹 페이지(Static Web Page)로 구성된 사이트 즉, HTML, CSS, JavaScript로만 만들어진 사이트를 말한다. 이 정적 사이트를 생성하는 도구가 정적 사이트 생성기다. 정적 사이트 생성기를 사용하면 문서화 도구처럼 HTML로 결과물을 얻을 수 있고 템플릿도 직접 개발할 수 있다. 깃헙 페이지(GitHub Pages)에 익숙한 사람들이라면, 정적 사이트 생성기로 Jekyll을 많이 사용해보았을 것이다. 최근에는 다양한 정적 사이트 생성기가 오픈 소스로 제공되고 있다.

우리는 정적 사이트 생성기를 내장해 자바스크립트 API 문서를 생성할 수 있는 랩퍼(Wrapper)를 만들기로 했다. 랩퍼의 구조를 정리해보면 다음과 같다.

Gatsby의 선택

남은 일은 어떤 정적 사이트 생성기를 사용할지 결정하는 것이다. Gatsby와 Docusaurus가 후보에 올랐다. 둘 다 컨트리뷰션이 굉장히 활발한 오픈 소스로, 템플릿을 만들 때 React를 사용하여 컴포넌트 개발이 가능하다. 또한 CLI 및 옵션 설정으로 페이지 생성과 배포가 쉬운 점이 공통된 장점으로 꼽힌다.

Docusaurus가 Gatsby 보다 문서 버전 관리 및 CI 설정이 용이해서 문서화 도구로 더 적합해 보였지만 UI 확장에 제한이 많았다. 예를 들어 LNB, 헤더는 리액트 컴포넌트로 개발하는 대신 옵션으로 설정해야 했다(여전히 템플릿의 장벽이 존재 했다). 그리고 가장 큰 문제로, 문서 내에서 사용되는 데이터가 마크다운만 가능하기 때문에 원하는 디자인으로 문서를 만들기 어려웠다.

이에 반해 Gatsby는 우리가 구현하려는 기능들을 모두 가능하게 만들었다. 아래 이미지는 Gatsby의 워크플로우를 보여주는데, 전체적인 흐름은 다른 정적 사이트 생성기와 차이가 없어 보이지만 사용된 기술 스택만큼은 그 어느 도구보다도 강력하다.

(출처 : https://www.gatsbyjs.org/)

Gatsby의 주요 기능들을 정리해보면 다음과 같다.

SPA 개발

Gatsby를 사용하면 GraphQL과 React로 SPA(Single Page Application) 개발이 가능하다. GraphQL은 데이터 소스로부터 데이터를 가져오는 역할을 하며, Gatsby에서 GraphQL을 쉽게 사용할 수 있는 방법을 제공한다. 또한 React를 내장하고 있어 컴포넌트 개발이 가능하다. 일반적인 React 앱을 만들 때와 동일한 환경으로 개발할 수 있다.

다양한 플러그인 지원

Gatsby 플러그인을 사용하여 개발에 들어가는 공수를 줄여준다. 예를 들어, 코드 하이라이팅에 필요한 설정을 직접 하는 것이 아니라 gatsby-remark-prismjs 플러그인을 설치하고 코드에서 바로 사용하기만 하면 된다.

편리한 빌드 과정

Gatsby는 CLI를 제공하여 개발 및 빌드를 쉽게 할 수 있도록 도와준다. Gatsby는 Webpack을 사용해 정적 사이트를 생성하며, Webpack 설정 옵션이 내장되어 있어 사용하는 입장에서는 Gatsby 명령어만 실행하면 된다. 만약 세부 설정이 필요하다면 Gatsby에서 제공하는 설정 파일로 확장해서 사용할 수 있다. 데브 서버도 제공하여 로컬에서 실시간으로 사이트를 확인하며 개발할 수도 있다.

정적 사이트로 배포

SPA로 개발된 사이트는 빌드되는 동안 접근할 수 있는 경로에 대해 서버 렌더링 된 페이지를 만들어낸다. 이런 과정으로 정적 사이트가 만들어지고, SPA를 지원하지 않는 깃헙 페이지에도 사용이 가능하다.

Gatsby를 새 문서화 도구에서 사용했을 때 이점을 정리해보면 다음과 같았다.

1. GraphQL과 플러그인을 사용해 데이터를 JSON으로 처리할 수 있다. 즉, documentation.js에서 파싱한 데이터를 사용할 수 있다.
2. React 컴포넌트로 템플릿을 만들어 하나의 앱으로 깔끔하게 관리할 수 있다.
3. 생성된 문서는 SPA이기 때문에 전체 페이지를 리프레쉬해야 하는 다른 도구로 만든 문서에 비해 빠르고 사용자 경험이 더 좋다.

Gatsby는 새 문서화 도구에서 요구하는 기능들을 처리하는 데 적합했다.

TOAST UI Doc의 탄생

이로써 JSDoc Template을 대체하기 위한 그림이 그려졌다. documentation.js와 Gatsby의 조합과 함께 TOAST UI Doc(패키지명: @toast-ui/doc) 이라는 이름으로 새 문서화 도구를 만들 수 있게 되었다.

TOAST UI Doc을 사용하면 좋은 몇 가지 이유

TOAST UI Doc은 JSDoc Template의 기능적인 장점을 살리면서 한층 업그레이드된 디자인이 더해진 문서화 도구이다. TOAST UI Doc은 단순히 자바스크립트 API 문서의 역할만 하지 않는다. 지금부터는 TOAST UI Doc을 자세히 들여다보면서, TOAST UI Doc이 제공하는 멋진 기능들을 소개하겠다.

어썸(Awesome)! 디자인

API 문서의 역할은 문서를 통해 개발자가 얻고자 하는 API 정보를 쉽게 파악할 수 있어야 한다. 단순히 폰트 크기나 색상 변경만으로는 가독성 문제를 해결하지 못한다. API 종류에 따라 어떻게 효과적으로 보여줄지 UI도 잘 설계되어 있어야 한다. TOAST UI Doc은 이러한 사항들을 고려하여 효과적으로 API를 보여줄 수 있도록 디자인 개선에 신경 썼다.

다음은 실제로 TOAST UI Grid의 API 문서에 TOAST UI Doc을 적용한 모습이다. 이전에 사용했던 JSDoc Template나 documentation.js 템플릿과 비교했을 때, TOAST UI Doc으로 만들어진 문서에서 API 정보가 훨씬 더 눈에 잘 들어올 것이다.

TOAST UI Doc에서는 다음과 같은 요소들이 가독성을 높여준다.

세분화 된 LNB 메뉴 구성

TOAST UI Doc의 LNB는 중추 역할을 한다. LNB 메뉴를 통해서 문서 내 각 페이지로 이동하는 것이 주요 기능이지만 이보다 더 중요한 기능이 있다. LNB 메뉴를 통해서 현재 라이브러리에서 사용하고 있는 구현체의 종류와 각 구현체의 API 정보를 파악 할 수 있다. TOAST UI Doc은 7가지 구현체 와 5가지 API 타입 을 제공하며, 코드에 정의된 JSDoc 정보에 따라 LNB 메뉴가 구성된다.

• 7가지 구현체 (메인 메뉴)

  • MODULES
  • EXTERNALS
  • CLASSES
  • NAMESPACES
  • MIXINS
  • TYPEDEF

• 5가지 API 타입 (서브 메뉴)

  • EXTENDS
  • MIXES
  • STATIC PROPERTIES
  • STATIC METHODS
  • INSTANCE METHODS
  • EVENTS

깔끔한 파라미터 노출 방식

인스턴스를 생성하거나 메서드를 호출할 때 사용되는 파라미터는 가장 중요한 API 정보다. 파라미터가 객체 타입이면서 하위 프로퍼티의 뎁스가 깊은 경우에는 문서 안에서 정보를 한 눈에 알아보기 어렵다. 이러한 문제를 해결하기 위해 TOAST UI Doc에서는 다중 테이블을 사용하여 파라미터 정보를 보여준다. 또한 옵셔널(optional) 및 기본값은 테이블 컬럼을 사용하는 대신 [foo], bar = 0과 같이 구문을 사용하고, 타입(number, boolean, string, array, object, function, 그 외 참조 타입)마다 다른 색상을 사용하여 파라미터를 쉽게 구분할 수 있도록 도와준다.

다양한 강조 기능

이 외에도 LNB 메뉴 상태 표시, 아이콘, 코드 하이라이트 등 어떤 API 정보도 놓치지 않고 전달할 수 있도록 요소 강조 방법도 고려했다. 특히 코드 하이라이팅은 TOAST UI 브랜드 컬러 조합을 통해 만들어진 것으로 다른 코드 하이라이트 테마보다 가독성이 뛰어나다.

Examples 페이지로 라이브러리 맛보기

컴포넌트 단위의 자바스크립트 라이브러리의 경우, 직접 사용해보고 사용 방법도 확인할 수 있는 페이지가 있으면 좋을 것이다. TOAST UI Doc에서는 Examples 페이지 를 통해 이러한 기능들을 제공한다. LNB 상단에 위치한 'Examples' 탭 메뉴를 통해 다양한 예제 페이지에 접근할 수 있으며, 각 페이지는 간단한 데모뿐만 아니라 자바스크립트 라이브러리를 사용할 때 필요한 스크립트 및 마크업 코드를 확인해볼 수 있도록 구성되어 있다. TOAST UI Doc을 사용하면 API와 Examples 페이지를 따로 관리할 필요가 없다. LNB 탭 메뉴 이동만으로 원하는 정보를 보고, 찾고, 체험해볼 수 있다.

편리하게 검색하기

TOAST UI Doc은 문서 내에 있는 API를 검색할 수 있도록 검색 기능을 제공한다. LNB 상단에 위치한 검색 바(bar)를 통해서 문서 내에 있는 모든 API와 Examples 페이지 목록 검색이 가능하다. 검색 바에 키워드를 입력하면 검색 목록이 노출되며, 검색어 자동 완성 기능을 통해 사용자는 문서에 있는 정보를 빠르고 편리하게 검색할 수 있다.

퍼머링크로 코드 자세히 보기

퍼머링크(Permalink)는 고유 주소(Permanent Link)의 약자로, 특정 페이지에 영구적으로 할당된 URL을 의미한다. 깃헙에서는 소스 코드에 대한 퍼머링크를 제공하며, TOAST UI Doc에서는 이 퍼머링크를 통해 API 문서에서 원본 소스 코드로 연결해주는 기능을 제공한다. 각 API 영역의 오른쪽 상단에 JSDoc이 작성된 소스 코드의 파일명 및 라인 정보가 링크 형태로 표시된다. 이 링크를 클릭하면 실제 코드가 위치한 깃헙 리포지터리로 이동한다. JSDoc이 작성된 API의 세부 구현 내용을 확인할 때 유용하다.

TOAST UI Doc 사용 방법

TOAST UI Doc이 만들어진 배경, 장점 등을 알아보았으니 이제는 직접 사용해보자. TOAST UI Doc 사용 방법은 간단하다.

설치 및 환경 설정

먼저, TOAST UI Doc을 npm 글로벌로 설치한다.

$ npm install -g @toast-ui/doc

다음은 문서를 생성할 프로젝트 폴더로 이동해, 루트에 환경 설정 파일(tuidoc.config.json)을 생성한다. 이 환경 설정 파일에 문서를 생성할 때 필요한 정보를 설정한다. 각 옵션에 대한 설명과 값 정보는 링크를 참조한다.

project/
  ├─ ...
  ├─ package.json
  └─ tuidoc.config.json

JSDoc 작성

TOAST UI Doc이 실행되면 documentation.js는 자바스크립트 파일에서 JSDoc을 파싱하여 JSON 데이터로 가공한다. API 정보에 맞게 JSDoc을 작성한다. 아래 예제에서는 MyDoc 클래스와 멤버인 getValue() 메서드 정보가 생성될 것이다. 데모 코드를 확인하면 다양한 방식으로 예제를 작성해볼 수 있다.

/**
 * @class MyDoc
 */
class MyDoc {
  constructor() {
    /**
     * @type {string}
     * @private
     */
    this.title = 'Hello TOAST UI Doc!';
  }

  /**
   * Returns value of title.
   * @returns {string} Title of MyDoc class
   */
  getValue() {
    return this.title;
  }
}

문서 생성

TOAST UI Doc은 문서를 편리하게 생성할 수 있도록 CLI를 제공한다. tuidoc 명령어를 실행하면 문서를 생성하고, --serve 옵션을 사용하면 생성된 문서를 로컬 서버에서 확인할 수 있다. package.json에 다음과 같이 스크립트를 추가한다. 정상적으로 문서 생성이 완료되었다면, 루트 아래에 _latest, _[SemVer] 2가지 이름으로 폴더가 생성된 것을 확인할 수 있다. 이렇게 생성된 폴더를 깃헙 페이지 또는 서버에 업로드하면 모든 과정이 끝난다.

npx tuidoc

어떤가? 정말 간단하지 않은가? 당신의 첫 번째 TOAST UI Doc 문서가 만들어졌다!

맺음말

TOAST UI Doc은 1년이라는 시간에 걸쳐 장기간으로 진행된 프로젝트였다. Gatsby v1.0으로 시작해 개발을 진행하다 메이저 버전으로 업데이트 하면서 난항을 겪기도 했었고, 개발 완료 시점에는 TOAST UI의 전 제품에 적용하면서 누락된 부분들은 없는지 체크하는 과정이 출시일을 더디게 만들었다. 늘 그렇듯이 어려움은 있고 고비도 찾아온다. 그럼에도 불구하고 TOAST UI Doc을 개발하며 거쳐온 모든 과정은 문서화 도구의 A부터 Z를 알게 만들어 준 아주 값진 경험 이 되었다. TOAST UI Doc으로 TOAST UI 문서를 안녕하게 만들었으니, 이제 당신이 만든 자바스크립트 라이브러리의 API 문서도 안녕하게 만들어보길 바란다. 💪

다운로드는 여기에서 할 수 있다.