技術文書をAsciidoc で書いて、GitlabでCIしている話

うちのチームでは、AsciiDoc で仕様書や技術メモを書きGitlab で管理しています。
あるとき、Redpenを紹介されたのを機会に、ドキュメントのCIを回すようにしたので、そのお話です。

AsciiDoc って？

軽量マークアップ言語の一つです。
以下のような過程を経て、AsciiDocを利用するようになりました。

1. Word を共有フォルダで管理
   • 重い。差分管理しづらい。同時編集がしづらい
2. Markdown をgitlabで管理
   • 軽い。Gitで編集履歴が簡単に確認可能。
   • Gitlab上で、整形された状態でプレビュー可能。
   • 方言がある（エディタのプレビューではきちんと表示されても、gitlab上で崩れる）
   • テーブルの編集が大変（特に更新の時が。。。）
3. AsciiDoc をgitlabで管理
   • 軽い。Gitで編集履歴が簡単に確認可能。
   • テーブル編集が楽。複雑な構造のテーブルもかける。Asciidoc簡易メモ#テーブル
   • Gitlab上で、整形された状態でプレビュー可能。ただし、ちょこちょこおかしい（後述）。

Redpen って?

赤ペン先生ですね
http://redpen.cc

検出設定などかなり細かい設定が可能です。
ただし、教えてくれた人に設定ファイルをもらい、ほぼそのまま使っているので詳しくありません。

動作イメージ

1. Gitlab にpush
2. 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 に公開

結果

• Gitlab でのプレビュー link
• Gitlab Pages link
• Redpen の結果は、GitlabのPipeline から確認 link

おわりに

表記ゆれなどを指摘してくれるので、レビュー時は内容に集中できるようになりました。

ただ、以下のような課題も残っています。

• 個々のページになっているので、ひとつのPDFとかに再変換できない。
• gitlabのプレビューでは、少し残念なところがある
  • アイコンが表示されない issue
  • 内部リンクが作動しない issue
  • umlを表示するには、gitlabの設定が必要
• Redpen の設定ファイルを一から作成するのは大変そう。
• Redpen の誤指摘。suppressアノテーションをつけるとエラーを抑止できますが、その節自体チェックが行われなくなり、将来の検出漏れを埋め込む可能性があります。