[Slate] API Document Tool로 Slate 사용하기

하나의 class를 온전히 혼자 맡아서 구현한 이후, 다른 팀원들에게 설명을 하거나 코드 정리가 나름대로 필요할 때 API 문서 작성의 필요성을 많이 느낀다.
doxygen을 써보려고 했지만, 함수마다 주석을 다는것은 가독성을 해칠 것 같아 좋은 방법을 찾아 보던 중 Slate를 알게 되었다.

---

Slate란?

• Ruby 기반의 HTML 실시간 렌더링, 빌드 기능을 가진 애플리케이션이다. API Tooling할 때 쉽게 적용할 수 있는 장점이 있어서 선택하게 되었다.

• /source 디렉토리의 Markdown 문서들을 기반으로 API 문서를 작성하면 Slate에서 반응형 웹으로 변환해준다.

• 실시간으로 마크다운 문서를 확인할 수 있고 배포를 위한 HTML 빌드 기능도 제공한다.

• 예시 페이지 : https://slatedocs.github.io/slate/#introduction

Slate Install

• 어떤 운영체제에서도 개발이 가능하지만 개발 환경 구축은 Ubuntu가 익숙하기 때문에 나는 Ubuntu 20.04 에서 개발 환경을 구성했다.

1. Ruby, Bundler 설치

$ cd ~
$ sudo apt-get install -y ruby-2.3.4-1.el6.x86_64.rpm
$ sudo apt-get install ruby-bundler
$ bundle install

2. Node.js 설치

$ sudo apt install nodejs
$ nodejs -v
$ sudo apt install npm

3. Slate 설치

• slate github을 나의 리포지토리로 fork 해온다.
  https://github.com/slatedocs/slate
  

$ git clone https://github.com/Krystalvv/slate.git
$ cd slate

4. Bundle 실행

# 코드를 받아오고 한번만 실행해주면 된다.
$ bundle install

Slate 설치가 완료되었으면 /source/index.html.md와 /includes/*.html.md를 작성하여 API 문서를 작성하면 된다.

5. Slate Server 구동

$ bundle exec middleman --watcher-force-polling

6. Slate Build

$ bundle exec middleman build --clean

• 작성이 완료된 API 문서를 빌드하려면 아래와 같이 실행한다. /build 디렉토리에 진입점이 되는 index.html과 기타 파일들이 생성된다. 빌드된 파일들을 클라이언트에게 전달하거나 웹사이트에 배포하면 된다.

---

⚠ trouble shooting

번외로 Slate 사용을 위한 환경 구축 중에... 번거로운 일들이 많았다. 문제 해결은 아래 링크들을 참조했다.

• Type Error : https://stackoverflow.com/questions/70364903/superclass-mismatch-for-class-command

 2186  sudo dpkg -r --force-depends ruby-thor
 2187  gem install thor

• SSL Certificates 문제(https -> http) : https://pinedance.github.io/blog/2017/11/02/how-to-bypass-SSL