설정 파일

documentation-generator로 빌드를 하려면 소스 디렉터리나 결과 디렉터리, 문서 계층 구조 등을 표시한 설정 파일이 있어야 한다. 옵션을 주지 않으면 기본적으로 프로젝트 디렉터리에서 documentation-generator.config.js를 찾는다. 설정 파일이 다른 경로에 있다면 --config 옵션을 통해 절대 경로나 프로젝트 디렉터리에 상대적인 경로를 제공해야 한다.

설정 파일은 JavaScript로 작성되며 다음과 같은 객체를 export 해야 한다.

{
	name: string,
	src: string,
	dst: string,
	template?: string,
	templateData?: {
		[key: string]: any
	},
	render: (text: string) => string,
	list: ListType = (
		{name: string, file: string} 
		| {name: string, dir: string, list: ListType}
	)[];
}

각각의 속성의 의미는 다음과 같다.

name: string: 설명서의 이름. 이 설명서에서는 “documentation-generator 설명서”이다.
src: string: 소스 파일이 있는 디렉터리. 절대적이거나 프로젝트 디렉터리에 상대적이어야 한다.
dst: string: 빌드된 HTML 파일이 위치할 디렉터리. 절대적이거나 프로젝트 디렉터리에 상대적이어야 한다.
template: string (optional): HTML 파일의 템플릿으로 사용할 EJS 파일의 경로. 절대적이거나 프로젝트 디렉터리에 상대적이어야 한다. 제공되지 않으면 기본 템플릿이 사용된다.
templateData: { [key: string]: any } (optional): 템플릿에 넘길 데이터. 기본 템플릿에는 다음과 같은 값을 넘길 수 있다.
- styles: string: link나 style 태그 등의 HTML 코드
- scripts: string: script 태그 등의 HTML 코드
render: (text: string) => string: 코드를 입력받아 HTML을 렌더링하는 함수.
list: ListType: 문서의 계층 구조를 나타내는 배열. 배열의 원소는 하나의 파일 또는 디렉터리를 나타낼 수 있다.
- 파일을 나타낼 경우
```
{
	name: 목차에 나타날 이름,
	file: 파일 이름
}
```
  파일 이름으로 index를 쓸 수 없다.
- 디렉터리를 나타낼 경우
```
{
	name: 목차에 나타날 이름,
	dir: 디렉터리 이름,
	list: ListType
}
```
  list에는 재귀적으로 파일 또는 디렉터리의 배열이 들어간다.

이 설명서가 지금 사용하고 있는 설정은 다음과 같다.

npm install yamd@0.4 katex@0.15 highlight.js@10

var fs = require('fs'),
	path = require('path');

// Finds out the version of a module.
function getVersion(name) {
	var dir = path.dirname(require.resolve(name));

	while (!fs.existsSync(path.join(dir, 'package.json'))) {
		dir = path.resolve(dir, '..');
	}
	
	return require(path.join(dir, 'package')).version;
}

var yamd = require('yamd'),
	hljs = require('highlight.js'),
	katex = require('katex');

yamd.set({hljs, katex});

var styles = `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/highlight.js@${getVersion('highlight.js')}/styles/tomorrow.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@${getVersion('katex')}/dist/katex.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/yamd@${getVersion('yamd')}/web/yamd.default.css">`;

module.exports = {
	name: 'documentation-generator 설명서',
	src: 'src',
	dst: 'build',
	render: text => yamd.render(text),
	templateData: {
		styles
	},
	list: [
		{
			name: '소개',
			file: 'introduction.yamd'
		},
		{
			name: '설정 파일',
			file: 'config-file.yamd'
		},
		{
			name: '커스텀 템플릿',
			file: 'templates.yamd'
		},
		{
			name: '꿀팁',
			file: 'honeytip.yamd'
		},
	]
};

디렉터리 구조는 다음과 같다.

documentation-generator/docs
├ build
├ src
│ ├ config-file.yamd
│ ├ honeytip.yamd
│ ├ introduction.yamd
│ └ templates.yamd
├ documentation-generator.config.js
└ package.json 등

빌드를 하면 build 디렉터리가 다음과 같이 된다.

build
├ config-file.html
├ honeytip.html
├ index.html
├ introduction.html
└ templates.html

index.html은 루트 디렉터리를 위해 자동으로 생성된 것이다. 이는 모든 디렉터리에 대해 생성된다.