うちのチームでは、AsciiDoc で仕様書や技術メモを書きGitlab で管理しています。
あるとき、Redpenを紹介されたのを機会に、ドキュメントのCIを回すようにしたので、そのお話です。
AsciiDoc って？
軽量マークアップ言語の一つです。
以下のような過程を経て、AsciiDocを利用するようになりました。
- Word を共有フォルダで管理
-
重い。差分管理しづらい。同時編集がしづらい
- Markdown をgitlabで管理
-
軽い。Gitで編集履歴が簡単に確認可能。 -
Gitlab上で、整形された状態でプレビュー可能。
-
方言がある（エディタのプレビューではきちんと表示されても、gitlab上で崩れる）
-
テーブルの編集が大変（特に更新の時が。。。）
- AsciiDoc をgitlabで管理
-
軽い。Gitで編集履歴が簡単に確認可能。
-
テーブル編集が楽。複雑な構造のテーブルもかける。Asciidoc簡易メモ#テーブル
-
Gitlab上で、整形された状態でプレビュー可能。ただし、ちょこちょこおかしい（後述）。
Redpen って?
赤ペン先生ですね
http://redpen.cc
検出設定などかなり細かい設定が可能です。
ただし、教えてくれた人に設定ファイルをもらい、ほぼそのまま使っているので詳しくありません。
動作イメージ
- Gitlab にpush
- Gitlab CI により、Redpenで校正チェック。ついでに、AsciiDoc をHTML変換 + pagesに公開
サンプル
フォルダ構造
.gitlab-ci.yml
src/ ・・・原稿・画像を格納するフォルダ
image/
build.sh ・・・AsciiDoc から Html への変換するスクリプト
reopen-conf-ja.xml ・・・Redpenの設定ファイル
各ファイル詳細
build.sh
#!/bin/bash
asciidocfiles () {
dist="public/${1#src/}/.."
asciidoctor -a ext=html -r asciidoctor-diagram -D $dist $1
}
export -f asciidocfiles
find src -name "*.adoc" | xargs -I{} bash -c "asciidocfiles {}"
cp -r src/images public
原稿のファイル構造を保ったまま処理するために、adocを検索しひとつづつ出力先を指定して変換。
イメージファイルはフォルダごとコピー
また、Gitlabのプレビュー、変換後のHTML両方でファイル間のリンクを保つために、執筆時に以下のような小細工をしています。
- 文書の先頭に
:ext: {adoc}を定義 - リンクは、
link:index.{ext}[xxx]のように書く - asciidoctor での変換時に
-a ext=htmlオプションを追加
.gitlab-ci.yml
test:
image: wreulicke/redpen:1.9.0
script:
- find src -name "*.adoc" | xargs redpen -f asciidoc -l 0 -c redpen-conf-ja.xml 2> redpen.log
artifacts:
paths:
- redpen.log
expire_in: 1 week
pages:
image: asciidoctor/docker-asciidoctor:latest
script:
- ./build.sh
artifacts:
paths:
- public
only:
- master
２つのジョブを定義
- check: Redpen で文書チェック
- Error が１つでも見つかると、エラーになります。(-l オプションで閾値は変更可能）
- pages: build.sh を実行し、html変換 + pages に公開
結果
おわりに
表記ゆれなどを指摘してくれるので、レビュー時は内容に集中できるようになりました。
ただ、以下のような課題も残っています。