スタイルガイドジェネレーターの hologram を試してみた

2014-10-15

スタイルガイドジェネレーターの hologram を試してみた

スタイルガイドを作成するジェネレーターもいろいろとあるのですが、 CodeGrid で @Takazudo 先生が Hologram について紹介をしていたので、良さそうな感じもあったので、ひとまず試してみることにしました。

Hologram — Style Documentation Build System

hologramでカスタムスタイルガイド – 機能概要 | CodeGrid

hologram のインストール

hologram は Ruby で動かすようなので、Ruby をインストールしておきます。

Ruby の入った環境で、 hologram をインストールします。

$ gem install hologram

複数人でプロジェクトを進めるような場合は、 Gemfile を作成しておいて、それを利用してインストールするようにしておくようにしましょう。

Gemfile

source 'https://rubygems.org'
gem 'hologram'

bundler を使ってインストールするのですが、インストールされていない人は先に bundler をインストールしておきます。

$ gem install bundler

bundler

bundler を使ってのインストールは以下のコマンドになります。利用する場合は bundle となるんので要注意です。

ひとまずこれでインストールは完了

設定ファイルなどの準備

次に設定ファイルなどを用意します。すでにあるサンプルプロジェクトから持ってきてもよかったのですが、デフォルトの中身も知っておきたかったので、まずは hologram init をしてみようと思います。

$ hologram init

以下のファイルが作られます

hologram_config.yml
doc_assets
- _header.html
- _footer.html

設定まわりは hologram_config.yml に書くようなので、これを確認します

設定ファイルの確認

hologram_config.yml

# Hologram will run from same directory where this config file resides
# All paths should be relative to there

# The directory containing the source files to parse recursively
source: ./sass

# The directory that hologram will build to
destination: ./docs

# The assets needed to build the docs (includes header.html,
# footer.html, etc)
# You may put doc related assets here too: images, css, etc.
documentation_assets: ./doc_assets

# Any other asset folders that need to be copied to the destination
# folder. Typically this will include the css that you are trying to
# document. May also include additional folders as needed.
dependencies:
  - ./build

# Mark which category should be the index page
# Alternatively, you may have an index.md in the documentation assets
# folder instead of specifying this config.
index: basics

デフォルトでは、sass ディレクトリのファイルをみて、docs ディレクトリに出力、 doc_assets をテーマとして利用するようです。出力時に加えたいフォルダなどがあれば、dependencies に書き入れるようです。

作成された _header.html をみると、ページの頭に入る部分ができている様子です。link のスタイルシートに your_stylesheet_here.css とあるので、 ../sass/demo.css とでもしようと思います。また、日本語を入れると文字コードでうまく表示されない可能性も考慮して、meta タグで charset="UTF-8" の指定しておきます。 sass フォルダに .css というおかしな状況ですが、とりあえずデモ作成用として。

一度実際に build してみようと思います。

ビルド

デフォルト設定どおりにすると sass フォルダに作成することになりますので、デモなので、フォルダを作成して demo.css を以下のように用意してみようと思います。

/*doc
---
title: Buttons
name: Base button
category: Buttons
---

ボタンのスタイル、`<button>` もしくは `<a>` で利用。

```html_example
<button class="btn">button</button>
<a class="btn" href="#">button</a>
```

*/
/* Base button */.btn {
  font-family: Lucida Grande;
  padding: 10px 20px;
  margin: 0;
  display: inline-block;
  font-weight: normal;
  font-size: 14px;
  text-decoration: none;
  line-height: 1;
  cursor: pointer;
  border: 0;
  background: #ccc;
  text-align: center;
  border: 1px solid #999;
  border-radius: 4px;
  color: #333;
}

/*doc 〜*/ でドキュメントになる部分を指定して、ビルドします。ビルドは hologram コマンドを叩くのみです。

$ hologram
Warning: Could not generate index.html, there was no content generated for the category basics.
Warning: Could not copy dependency: ./build
Build completed. (-:

デフォルトのままで上記のファイルのみで作成をすると、 Wraning が２つでてきます。 index.html が作られてないよーというのと、buildフォルダないからコピーしてないよーという内容ですので、ひとまず気にせずに。

出来上がったファイルの確認

ビルドが成功すると、docs/button.html というファイルが出来上がっているので、ブラウザで開いてみます。

で、でてきた？？？

まぁ、 _header.html の link である程度予想していたのですが、デフォルトテーマ的なのってないのですね。

Github trulia/hologram-example

この example を落としてきて利用することで、このようなスタイルになるということが確認できました。

あとはこれをもう少し使いやすくするために、スタイルを調整して、それぞれのプロジェクトに合わせたり、独自にテーマにしてしまって使うとということになるのですね。

ひとまず、どのように動作するのかなどは確認できたので、もう少し使い込む & 見た目調整などもして、最終的に利用できるようにしたいと思います。

余談：gulp での連携もしてみた

gulp の連携をさせようと思い、プラグインあるかなーと探したのですが、どうも設定ファイルを読み込むようなものなだけ？な様子なので、プラグイン使わずにシンプルに child_process の spwan メソッドで渡せばよいかなと。

var cp = require('child_process');
cp.spawn('hologram').on('close', reload);

reload は browser-sync を使っている場合などの reload のを別途指定あるのでそれを利用している部分ですが、上記では省略。

毎回プラグイン探したりももちろんしますが、いいものがなければシンプルに終わらせるでも十分かなと。

参照：