Help us understand the problem. What is going on with this article?

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

More than 1 year has passed since last update.

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

AsciiDoc って?

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

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

Redpen って?

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

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

動作イメージ

  1. Gitlab にpush
  2. Gitlab CI により、Redpenで校正チェック。ついでに、AsciiDoc をHTML変換 + pagesに公開

サンプル

https://gitlab.com/hgs/doc-sample

フォルダ構造

.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

2つのジョブを定義

  • check: Redpen で文書チェック
    • Error が1つでも見つかると、エラーになります。(-l オプションで閾値は変更可能)
  • pages: build.sh を実行し、html変換 + pages に公開

結果

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

おわりに

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

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

  • 個々のページになっているので、ひとつのPDFとかに再変換できない。
  • gitlabのプレビューでは、少し残念なところがある
    • アイコンが表示されない issue
    • 内部リンクが作動しない issue
    • umlを表示するには、gitlabの設定が必要
  • Redpen の設定ファイルを一から作成するのは大変そう。
  • Redpen の誤指摘。suppressアノテーションをつけるとエラーを抑止できますが、その節自体チェックが行われなくなり、将来の検出漏れを埋め込む可能性があります。
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away