Underscore.js 프레임워크를 보면 소스에 대해 왼쪽에는 주석을 오른쪽은 소스를 보여주며 설명을 한다. 이러한 문서를 자동으로 만들어 주는 툴이 Groc 이다. 또한 루트에서 수행을 하면 하위의 모든 소스에 대한 문서화를 자동으로 만들어 주고, GitHub과 통합할 수 있다
1. Groc 설치하기
- 주석을 Markdown 형태로 작성한다
- 마크다운 포멧은 배우기 쉽고 GitHub에서도 사용하므로 반드시 익혀두자
- GitHub의 페이지 publishing 과 통합된다 : GitHub에서 OSS(Open Source Software) 개발한 것을 공짜로 웹 서비싱 해준다
- 검색 테이블을 제공한다
2. 설치하기
- npm (Node Package Manager)가 설치되어 있어야 한다
$ sudo npm install groc -g
npm http GET https://registry.npmjs.org/groc
npm http 304 https://registry.npmjs.org/groc
... 중략 ...
groc@0.3.2 /usr/local/lib/node_modules/groc
├── colors@0.6.0-1
├── spate@0.1.0
├── underscore@1.4.4
├── coffee-script@1.6.1
├── autorequire@0.3.4
├── showdown@0.3.1
├── optimist@0.3.5 (wordwrap@0.0.2)
├── jade@0.28.2 (commander@0.6.1, mkdirp@0.3.5)
├── uglify-js@2.2.5 (source-map@0.1.9)
├── glob@3.1.21 (inherits@1.0.0, graceful-fs@1.2.0, minimatch@0.2.11)
└── fs-tools@0.2.9 (async@0.2.6, lodash@1.0.1)
// syntax highlighting module pygments 설치하기
$ sudo easy_install Pygments
Best match: Pygments 1.6
Downloading http://pypi.python.org/packages/2.7/P/Pygments/Pygments-1.6-py2.7.egg#md5=1e1e52b1e434502682aab08938163034
... 중략 ...
Installing pygmentize script to /usr/local/bin <== groc가 사용함
3. 문서만들기
- * 사용할 수 있다
- 여러 옵션을 적용할 수 있다
- CLI 명령으로 수행한다 : groc [js명칭]
- github에서 groc를 다운받아서 직접 만들어 보자
//////////////////////////////
// groc 소스 받아 문서 생성하기
$ git clone https://github.com/nevir/groc.git
Cloning into 'groc'...
remote: Counting objects: 1215, done.
...중 략 ...
$ groc index.js
publish_to_github null https://github.com/nevir/groc origin
Generating documentation...
✓ /Users/git-repositories/groc/.git/groc-tmp/languages.html
✓ /Users/git-repositories/groc/.git/groc-tmp/project.html
..중략..
✓ /Users/git-repositories/groc/.git/groc-tmp/styles/default/docPage.html
✓ Documentation generated
//////////////////////////////
// 디렉토리별로 .js 또는 .coffee 파일을 .html 파일로 문서화 한다
// git clone 후
$ cd groc 디렉토리 이동후 모습
// groc 를 수행한 후의 디렉토리 : lib 디렉토리에 있는 폴더를 상위 폴더로 올린다
///////////////////////////
// static 웹서버 구동 (참조)
$ static
serving "." at http://127.0.0.1:8080
17:35:09 [200]: /
17:35:09 [200]: /assets/style.css
17:35:09 [200]: /assets/behavior.js
17:35:09 [404]: /favicon.ico
- 문서보기 : http://localhost:8080 Groc의 홈페이지 문서가 로컬에 만들어 졌다!
4. 사용 아이디어
- GitHub에서 소스를 개발한다면 GitHub Page와 통합하여 API를 웹서비스 형태로 배포한다
- 개발 소스에 대한 Code Review시에 Groc 문서로 만들어서 소스를 리뷰한다
<참조>