MkDocsによるドキュメント作成で便利な点

先日、社内ドキュメントを作成する際にMkDocsを使ってHTML形式のドキュメントを生成してみたのですが、なかなかに便利でしたので、紹介してみようと思います。

ドキュメント生成ツール、何使う？

システム開発におけるドキュメント作成に要する時間は、決して少なくありません。そのため、ドキュメントをできるだけ時間をかけずに、簡潔に書くことができる方法が求められるのではないかと思います。

私は以前はMicrosoft Wordを使って文書を書くことが多かったのですが、ここ最近になって、業務でのドキュメント作成にMarkdownが推奨されるようになってMarkdownで書き始めるようになってから、ちょっとWordはめんどくさいな、と感じるようになってきました。Wordは見出しなどを細かく設定できるメリットはありますが、逆に言えばレイアウトが崩れた時の調整がめんどくさかったり、文章以外の部分を気にしなければならないという問題を抱えています。

一方、Markdownは書き方のルールこそ、最初に覚える必要はありますが、覚えてしまえばサクサク書いていくことができます。HTMLに変換する際も、ルールに従って書いていればレイアウトが統一されるので、統一感のあるドキュメントになります。エディタによってはプレビュー機能を持つものもあるので、完成イメージを確認しながら書くこともできます。

MkDocsでMarkdownドキュメントをHTML化

MkDocsは、Markdownドキュメントを1つの静的なWebサイトに変換するツールです。MkDocs用のテーマがいくつか用意されており、目的に応じて最適なテーマを選ぶと良さそうです。

今回作成したドキュメントには、見出しごとにツリーで表現し、ツリーを展開できるWebページにしたかったので、「Read the Docs」というテーマを利用しました。MkDocsのビルド設定を行う”mkdocs.yml”に以下の様に設定を記述します。

site_name: MQPlatform ドキュメント

theme: 
  name: 'readthedocs'
  language: 'ja'


nav:
    - Top: index.md
    - 概要: summary.md
    - 仕様と制限事項: specifications_and_limitations.md
    - 管理者向け導入ガイド: admin_guide.md
    - ユーザ向け導入ガイド: user_guide.md
    - 操作マニュアル(Portal): manual_portal.md
    - 操作マニュアル(Studio): manual_studio.md
    - 個人情報保護ポリシー: privacy_policies.md

このように設定すると、以下のように、画面左部にツリーメニューが表示されます。