G* Advent Calendar 2013 1日目 - Gaiden
この記事は毎年恒例の G* Advent Calendar 2013 の1日目の記事です。1日目担当のyamakzuです。こんにちは。
今日は、先月10月頭にリリースしたGaidenについて紹介します。
GaidenはGroovy製の軽量ドキュメンテーションツールです。 この手のドキュメンテーションツールではSphinxやAsciiDocが有名ですが、ちょっとしたドキュメントを記述するには少し大きすぎるツールに感じるときがあります。
Gaidenはもっと簡単に気軽にドキュメントを記述できるようなツールを目指しています。 シンタックスにはMarkdownを採用しています。 Markdownでさっと書いて、ドキュメントを生成できる。そんなツールです。
とかいう表向きのセールストークはありますが、正直なところはGroovy使いとしてG製なツールが欲しかっただけです。
開発は主に@gantawitterと私、そしてid:nobeansのサポートのもと進めています。また、ドキュメントテンプレートの作成にid:labduckに協力してもらっています。
では早速使ってみましょう。
インストール
Groovy界隈ではお馴染みのGVMからインストールできます。
$ gvm install gaiden
WindowsではGVMが使えないのでバイナリをダウンロードして、展開したディレクトリのbin
ディレクトリにPATHを通してください。
プロジェクトの作成
まず始めにドキュメントのプロジェクトを作る必要があります。
create-project
コマンドで生成します。
$ gaiden create-project mydoc
$ cd mydoc
プロジェクトの構成は次のようになっています。
$ tree
mydoc
├── GaidenConfig.groovy : Gaidenの設定ファイル
├── pages : Markdownで書かれたページを格納するディレクトリ
│ ├── index.md
│ └── toc.groovy : 目次を定義するファイル
├── static : CSS、JSなどの静的ファイルを格納するディレクトリ
│ ├── ...
└── templates
└── layout.html : ページの雛形となるHTMLファイル
ページを記述する
ページはpages
ディレクトリ配下にファイル名.md
というファイル名でMarkdownで記述します。
試しにpages/mypage.md
を作り、次のように記述します。
# はじめてのGaiden
Gaidenやばい
ドキュメントを生成する
ページを記述したらドキュメントを生成してみましょう。
ドキュメントを生成するにはbuild
コマンドを実行します。
$ gaiden build
ドキュメントはbuild
ディレクトリに生成されます。
build/mypage.html
をブラウザで開いてみると次のような画面が生成されているはずです。
目次を作る
目次はpages/toc.groovy
に記述します。
次のように記述します。
"index.md"(title: "はじめに") {
"mypage.md"(title: "はじめてのGaiden")
}
もう一度gaiden build
を実行してbuild/toc.html
を開いてみてください。
次のようなページが表示されるはずです。
このtoc.groovy
はGroovyのDSLで記述します。
ページ名の文字列に続けて引数にtitle
という属性を設定していきます。
階層構造を持つ場合はクロージャ{}
を使って、ブロック内でページを指定します。
もう少し複雑な例では次ようになります。
"introduction.md"(title: "はじめに") {
"introduction/whatis.md"(title: "Gaidenとはなにか")
"introduction/install.md"(title: "インストール")
}
"quickstart/quickstart.md"(title: "クイックスタート") {
"quickstart/addingcontent.md"(title: "ページの生成")
}
テンプレートを編集する
ページのデザインを変更したい場合はtemplates/layout.html
を編集します。
Gaiden 0.3ではデフォルトで次のようなテンプレートになっています。
<html>
<head>
<meta charset="UTF-8">
<title>$title</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="${resource('/css/bootstrap.css')}">
<link rel="stylesheet" href="${resource('/css/prettify.css')}">
<link rel="stylesheet" href="${resource('/css/style.css')}">
</head>
<body>
<div class="navbar navbar-static-top">
<div class="container">
<a class="navbar-brand" href="$tocPath">$title</a>
<a class="toc btn btn-primary btn-lg" href="$tocPath"><span class="glyphicon glyphicon-list"></span></a>
</div>
</div>
<div class="container">
<section class="page-content">
$content
</section>
</div>
<footer id="footer" class="footer">
<div class="container">
<p class="credit text-muted">Powered by <a href="#">Gaiden</a>.</p>
</div>
</footer>
<script src="${resource('/js/jquery-1.10.2.min.js')}"></script>
<script src="${resource('/js/bootstrap.js')}"></script>
<script src="${resource('/js/prettify.js')}"></script>
<script src="${resource('/js/application.js')}"></script>
</body>
</html>
テンプレートの中では${resource(..)}
や$content
、$title
、$tocPath
といった拡張変数、メソッドが使えるようになっています。
詳しくはリファレンスを参照してください。
このHTMLを変更することで自由にデザインを変更できます。
今後について
まだまだ機能が少ない状況ですが少しずつ改善していく予定です。
年内には0.4をリリース予定です。 是非使ってフィードバックをください!
明日からは...
なんと3日間連続できょんくんです!どうしてそうなった! ではでは、よろしくお願いしますー