Docz

이번 포스트에서는 Docz에 대해 알아보려고 합니다.

Docz는 별도의 설정 없이 사용할수 있는 zero configuration 기반의 문서 생성 라이브러리입니다.
또한 mdx( markdown + jsx )라는 형식의 파일을 사용하고 있기 때문에
리액트를 사용하는 유저라면 더욱 더 손쉽게 배울 수 있습니다.

그리고 문서끼리는 의존성이 없고 각 문서가 컴포넌트에 의존하는 형식이기 때문에
프로젝트의 디렉토리 어느 위치에 .mdx 파일을 만들어도 상관이 없습니다.

Docz는 아래와 같은 장점을 가지고있다고 공식 홈페이지에 나와있습니다.

Zero config

Gatsby 테마 사용 가능

쉬운 커스터마이징

MDX 기반

최적화된 플러그인

타입스크립트 지원

위의 6가지 장점중에서
필자가 생각하기엔 MDX 기반의 Zero config 문서화 툴이라는게 가장 큰 장점이지 않을까 생각합니다.

설치 & 실행해보기

1
2
3

$ npm install docz doz-theme-default --save-dev
$ docz dev // docz dev
$ docz build // docz build

간단하게는 docz와 docz 테마를 설치 한 후
docz dev 명령어를 통하여 dev 서버를 실행할 수 있고,
docz build 명령어를 통하여 빌드를 할 수 있습니다.

문서 생성

앞서 말씀드린 것 처럼 문서끼리는 의존성이 없고 프로젝트 디렉토리 어디에든
.mdx파일을 만들어주기만 한다면 Docz는 mdx 파일을 찾아 빌드해주게 됩니다.


---
name: start
route: /
---

# 시작하기

## 설명을 시작합니다.

mdx파일을 만들고 dev 서버에서 확인을 해보면

docz

위와 같은 화면이 나오게 됩니다.
참고) mdx 문서에 route 설정을 해주었기 때문에 해당 페이지가 첫화면으로 노출되게 됩니다.

기본적인 문서 생성은 여기까지 이고,

이제는 간단하게 버튼을 만들어 문서화를 해 보도록 하겠습니다.

우선 구조는 어떤 구조이던 상관이 없습니다. 최상위 루트에 다 넣으셔도 상관없습니다.
하지만 필자는

docz
위와 같은 구조로 작성하도록 하겠습니다.

먼저 랜더링 할 버튼 컴포넌트를 만듭니다.

import React from 'react';
import PropTypes from 'prop-types';

import cx from 'classnames';
import styles from './Button.scss';

export default class Button extends React.Component {
  static defaultProps = {
    children: '',
    className: '',
    size: 'small',
    theme: 'default',
    type: 'button',
    disabled: false,
    onClick: () => {}
  };

  render() {
    const { className, children, type, theme, disabled, onClick } = this.props;
    return (
      <button
        className={cx(styles.button, styles[theme], styles[className])}
        type={type}
        onClick={onClick}
        disabled={disabled}
      >
        {children}
      </button>
    );
  }
}
Button.propTypes = {
  children: PropTypes.string,
  className: PropTypes.string,
  /** size type = "small | normal | big" */
  size: PropTypes.string,
  /** theme type = "default | primary | secondary | disabled | link | upload" */
  theme: PropTypes.string,
  /** button type = "button | submit | reset" */
  type: PropTypes.string,
  disabled: PropTypes.bool,
  onClick: PropTypes.func
}

후에 쓰일 docz의 Props 컴포넌트 사용을 위해 propTypes, defaultProps 을 정의 해 주면 좋습니다.
그리고 스타일링에 대한 플러그인을 설치 전 이기때문에 스타일링은 후에 넣어주셔도 됩니다.
(해당 버튼 컴포넌트는 작성자가 원하시는 코드를 작성하시고 위의 코드는 참고만 하시면 됩니다.)

다음으로 버튼 컴포넌트에 대한 문서만듭니다.
(mdx 문서이기 때문에 jsx처럼 사용할 수 있습니다.)

---
name: Button
route: /button  // 작성자가 원하는 경로 설정
---
import { Playground, Props } from 'docz';
import Button from './index.jsx';

# Button

## Basic usage
<Playground>
  <Button>default</Button>
  <Button theme="warning">warning</Button>
  <Button theme="primary">primary</Button>
  <Button theme="secondary">secondary</Button>
  <Button theme="link">link</Button>
</Playground>

## Props

### propName | type | init
<Props of={Button} />

작성한 mdx 문서를 보시면 jsx 처럼 컴포넌트를 import 하는것을 보실 수 있고,

<Playground>는 컴포넌트를 랜더링하고 사용된 코드를 보여주기위해 사용됩니다.
<Props>는 컴포넌트를 받아 해당컴포넌트의 props 테이블을 생성해줄때 사용됩니다.

그리고 처음에 작성한 Button 컴포넌트를 Playground를 사용하여 해당 컴포넌트를 랜더링해주면

docz

이런 화면이 랜더링 되게 됩니다.

추가로 커스터마이징을 하고싶으시다면
doczrc.js를 프로젝트 루트에 만드시고,
Docz 공식 홈페이지 커스터마이징 을 참고 하시면 됩니다.

이미 만들어져있는 테마를 사용하고 싶으시다면 Default 테마인 dark 와 light를 사용하시면 되고,
<playground>에 단독적으로 테마를 적용할 수 있는데
Codemirror 테마 URL에 나와있는 테마를 사용하시면 됩니다.

마무리

많은 사람들이 Docz와 StoryBook 그리고 Styleguidist 를 비교하고 있는데,
필자가 Docz를 선택한 이유는

문서화만 필요했기 때문에

MDX를 써보고 싶어서

Zero config가 편해서

이 3가지 이유 때문에 Docz를 사용하게 되었습니다.
개인적인 생각으로는 문서화만을 목적으로 한다면 Docz가 좋은것같고 다른 부가적인 기능이 필요하다면 StoryBook이 좋지 않을까 싶습니다.
(물론 Docz도 Stroybook 플러그인을 개발중입니다.)
이렇게 사용자의 목적에 따라 or 개인 취향에 따라 Docz, StoryBook, Styleguidist중 무엇을 사용할 것인지 판단하여 사용하시면 될 것 같습니다.

Docz

Docz

설치 & 실행해보기

문서 생성

마무리

Comments: