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をブラウザで開いてみると次のような画面が生成されているはずです。

f:id:yamkazu:20131129152118p:plain

目次を作る

目次はpages/toc.groovyに記述します。次のように記述します。

"index.md"(title: "はじめに") {
    "mypage.md"(title: "はじめてのGaiden")
}

もう一度gaiden buildを実行してbuild/toc.htmlを開いてみてください。次のようなページが表示されるはずです。

f:id:yamkazu:20131129152152p:plain

この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日間連続できょんくんです！どうしてそうなった！ではでは、よろしくお願いしますー