読者です 読者をやめる 読者になる 読者になる

Hologram を使ってスタイルガイドを作成してみた

Hologram とは

HologramRuby 環境で動くスタイルガイドジェネレータです。

.css.scss.sass.less.styl などの多様な形式のファイルに書かれたコメントから、自動でスタイルガイドを作ってくれます。

スタイルガイドは、静的な HTML ファイルとして出力され、独自のテンプレートを使ってスタイルガイドをカスタマイズすることもできます。

f:id:enomotodev:20170519204215p:plain

作業環境

  • CentOS 7.2
  • Ruby 2.3.1
  • Bundler 1.13.2
  • Sass 3.4.22

Hologram のインストー

プロジェクトの Gemfilegem "hologram" を追記します。

source "https://rubygems.org"

gem "sass"
gem "hologram"

追記したら bundle install しましょう。

$ bundle install

インストールが完了したので、バージョンを確認してみましょう。

$ hologram -v
hologram 1.4.0

Hologram の始め方

hologram init コマンドで hologram の設定ファイルなどが作成されるので、hologram init を実行してみます。

$ hologram init
Created the following files and directories:
  hologram_config.yml
  doc_assets/
  doc_assets/_header.html
  doc_assets/_footer.html
  code_example_templates/
  code_example_templates/markdown_example_template.html.erb
  code_example_templates/markdown_table_template.html.erb
  code_example_templates/js_example_template.html.erb
  code_example_templates/jsx_example_template.html.erb

色々とファイルが作成されましたが、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

# The folder that contains templates for rendering code examples.
# If you want to change the way code examples appear in the styleguide,
# modify the files in this folder
code_example_templates: ./code_example_templates

# The folder that contains custom code example renderers.
# If you want to create additional renderers that are not provided
# by Hologram (i.e. coffeescript renderer, jade renderer, etc)
# place them in this folder
code_example_renderers: ./code_example_renderers

# 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

# To additionally output navigation for top level sections, set the value to
# 'section'. To output navigation for sub-sections,
# set the value to `all`
nav_level: all

# Hologram displays warnings when there are issues with your docs
# (e.g. if a component's parent is not found, if the _header.html and/or
#  _footer.html files aren't found)
# If you want Hologram to exit on these warnings, set the value to 'true'
# (Default value is 'false')
exit_on_warnings: false
  • source
    .css.scss.sass.less.styl などのスタイルガイドを作成する元になるファイルが置かれているディレクトリを指定します。
  • destination
    作成されたスタイルガイド(HTML ファイル)を出力するディレクトリを指定します。
  • documentation_assets
    出力されるスタイルガイドのテンプレートを置くディレクトリを指定します。ここで指定したディレクトに置かれた _header.html_footer.html を使用して HTML ファイルが作成されるので、独自のテンプレートを作成したい場合は、_header.html_footer.html を編集するようなかたちになります。
  • code_example_templates
    CSS などでスタイルガイド用にコードを記述する時にフォーマットを指定できるのですが、例えば markup_example と指定した場合はここで指定したディレクトリの markup_example_template.html.erb を元にスタイルガイドを出力します。
    指定したファーマットのファイルが存在しない場合はデフォルトのテンプレートが使用されます。
  • code_example_renderers
    coffee_example など code_example_templates で指定できるフォーマット以外のフォーマットを使用したい場合は、ここで指定したディレクトリに coffee_example_template.html.erb などというかたちでファイルを作成します。
  • dependencies
    ここで指定したディレクトリのファイルはスタイルガイドを作成する際に documentation_assets で指定したディレクトリにコピーされます。
  • index
    スタイルガイドの TOP に表示するカテゴリーを指定することができます。
  • nav_level
    section または all を指定することでナビゲーションのレベルを変更することができます。all を指定すると sub-section まで表示することができます。
  • exit_on_warnings
    documentation_assets で指定したディレクトリに _header.html がない時など、エラーが発生して Hologram が終了する時に Warning を表示したい場合は true を指定します。

Hologram のサンプルを動かしてみる

Hologram には公式のサンプルがあるので、今回はそちらを動かしてみます。

まずは先ほどの hologram init コマンドで自動生成されたファイルを削除します。

$ rm -rf ./*

公式のサンプルを git clone します。

$ git clone git@github.com:trulia/hologram-example.git .

ビルドします。

$ hologram config.yml
Adding renderer for haml examples
Adding renderer for html examples
Adding renderer for js examples
Adding renderer for jsx examples
Adding renderer for react examples
Adding renderer for slim examples
Build completed. (-:

これで docs ディレクトリに HTML 形式でスタイルガイドが出力されたのでブラウザから確認してみます。

f:id:enomotodev:20170519204221p:plain

スタイルガイドの TOP を変更する

Hologram では source で指定したディレクトリ(.css.scss ファイルなどが置いてあるディレクトリ)直下に index.md を置くと、それをスタイルガイドの TOP として表示するようです。

index.md を削除して、Base CSS カテゴリーを TOP に設定してみましょう。

まずは index.md と先ほど作成した docs ディレクトリを削除します。

$ rm -rf components/index.md docs/

次に config.yml に追記して、『Base CSS』カテゴリーを TOP にするよう宣言します。

  • config.yml
...(略)
index: base_css

再度、ビルドします。

$ hologram config.yml
Adding renderer for haml examples
Adding renderer for html examples
Adding renderer for js examples
Adding renderer for jsx examples
Adding renderer for react examples
Adding renderer for slim examples
Build completed. (-:

ブラウザから確認してみます。

f:id:enomotodev:20170519204223p:plain

TOP にアクセスすると『Base CSS』カテゴリーがきちんと表示されました。

まとめ

Hologram はテンプレートを編集することによってスタイルガイドを自由にカスタマイズすることが可能です。

Hologram.css.scss ファイル内のコメントから自動で HTML を出力するので、wiki でよく見られる更新が滞りがちになるといったことも回避できるのではないかと思います。