techdoc-ja 日本語で技術ドキュメントを記述する環境整備

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

よく訓練されたアップル信者、都元です。弊社は本日を最終営業日として、これから冬季休業となります。 今年も一年、どうもありがとうございました。というわけで書き納めの一本、その3。

最近ドキュメントを書く機会が増えてきました。

  • 仕様書は Markdown で書きたいですね。そして GitHub を使って書き進めたいですね。
  • PlantUML で簡単に作図ができるといいですね。図中では日本語も使いたいですよね。
  • さらに機械的に実行できる校正は、自動チェックしたいですね。
  • 書き上がったものは自動的に HTML や PDF にして、S3 にデプロイしたいですね。
  • という一連のジョブは CI で実行したいですね。

という思いを実現するための環境を整えたので、ひとまず公開します。

どうやって実現するか

GitHub で Markdown は、まぁ単に書けって話ですよね。 書いたコンテンツは gitbook を使ってビルドします。 このあたりは以前も当ブログで紹介しているとおりです。

GitBook 環境を準備してみる

PlantUML による作図は gitbook-plugin-uml を使って実現します。 ただし、ビルド環境に graphviz が必須となります。 また、図中に日本語を使いたいとなると、フォントを考慮しておく必要があります。 ライセンスと個人的な趣味から MigMix フォントを利用することにしました。

この文法で Markdown の中に書いた UML は、残念ながら GitHub 上でプレビューできず、ただのコードブロックとして表示されてしまいます。 しかし、下記の Chrome 拡張を利用するとそのままプレビューできます。

GitHub 上で PlantUML をレンダリングするChrome拡張 v1.2.0 をリリースしました

gitbook は PDF を出力する機能を持っていますが、その場合はビルド環境に Calibre が必須となります。 また、作図と同じようにフォントの考慮も必要になります。

S3 への自動デプロイは aws-cli で sync すればいいですね。そして CI には Circle CI 2.0 を利用することにしました。

必要なソフトウェアと Docker イメージ

必要なものをまとめると、意外と多いですね。 これらをすべて、Circle CI 上から使うための Docker イメージを用意しました。

Docker としては、それぞれのイメージを用意するのが本来あるべき姿ではありますが、 今回は単一のイメージですべてを実行できることを目指しました。

という Docker イメージが DockerHub classmethod/techdoc-ja です。 Dockerfile は GitHub classmethod/techdoc-ja に上げてありますので、何かありましたら issue/PR ください。

サンプルプロジェクト

GitHub classmethod/techdoc-ja-example にサンプルプロジェクトを用意しました。

このプロジェクトは Circle CI のビルドを設定済みで、最後に S3 バケットへ成果物をデプロイします。

また、校正に引っかかる PR も用意してみました。 想定どおり CI が落ちていますね。

section4.md:34: ValidationError[JapaneseAmbiguousNounConjunction], 助詞「の」が連続しています: "〜システムの内容の詳細〜" at line: 本システムの内容の詳細は、以下の通りである。

また、RedPen が指摘する助詞の連続を修正しても textlint にはこのように指摘されます。

/root/workspace/content/section4.md
  34:14  ✓ error  以下の => 次の  prh
  34:17  ✓ error  通り => とおり  prh

✖ 2 problems (2 errors, 0 warnings)
✓ 2 fixable problems.

まとめ

これで、読みやすいドキュメントを書く環境が整ったと思います。書いていくぞ。

ちなみに「ドキュメントプロジェクト」ではなく、通常のソフトウェアプロジェクトであっても、 そこに含むドキュメントをソフトウェアの CI と並行して回すと良いと思います。

ソフトウェアの修正とドキュメントの修正をアトミックな PR として処理できるのは良いことですね。

ではみなさま、良いお年を。