Adways Advent Calendar 2018 14日目の記事です。
http://blog.engineer.adways.net/entry/advent_calendar_2018
こんにちは。2018年度新卒、二度めの登場、佐土原です。
早いのもので前回の記事からあっという間に3ヶ月が経ちました。 実家の母がこれを見つけ一瞬で連絡が飛んできて驚いたことにも懐かしさを帯びはじめる歳月です。母ちゃん今回も書いてるぞ。
さて、今回のブログでは僕の所属するチームで導入し始めたMkDocs + GitLabでのドキュメント管理について書いていこうと思います。
導入の背景
僕の携わるプロダクトも息の長いサービスとなってきており、日常的に「あの話はどうなったんだっけ?」「たしかここはこうだったよね?」という会話も増えてきました。 そこでチームとしてしっかりこれまで/これからの経過をドキュメントにまとめよう、という声が大きくなってきたのが発端です。
しかし当然過去にもこのような話が出たことはあり、「過去のドキュメント」と「これから作成するドキュメント」を管理する上で生じた問題がざっと以下のようなものでした。
- 過去のドキュメントが煩雑
いつ、だれが、なんのために書いたドキュメントが、どこにあるのかほとんど把握できていない状態でした。
- 既存管理ページのUIがつらい
過去のドキュメントはMarkdown記法で書いていたため、GitLabリポジトリWikiの項目に置いていました。ドキュメントの量が膨らみ、結果としてリンクだらけに。それでもMarkdownで書きたい。
- Confluenceとの同期が難しい
弊社で導入されているConfluenceにまとめればいいじゃない、という話もありますが、すでに過去のドキュメントがMarkdownで残ってるので移し替えのコストが高そうでした。あとMarkdownで書きたい。
↓これまでの管理ページ
つまり
Markdownで書きたい。
Markdownこそ正義。なんとしてでも。
そこで注目したのがMkDocsでした。
MkDocsとは
Markdown形式のドキュメントをもとに上記リンク先のような静的ページを生成してくれます。
ページの構成もディレクトリ構造をそのまま反映してくれるため直感的にページの管理をすることができます。なによりMarkdownで書ける。
そんなMkDocsをGitLab上のドキュメント管理用リポジトリに導入し、複数メンバーによる管理もしやすい静的ページを作ろう、というのが今回の狙いです。
導入手順
1. 新規GitLabリポジトリを作成
GitLabの"New Project"から新規リポジトリを作成します。
2. .gitlab-ci.yml
を編集
GitLab-CIによってMkDocsをビルドしてもらうので、以下のような内容を.gitlab-ci.yml
に記述します。
image: python:3.7 before_script: - pip install --upgrade pip - pip install --upgrade mkdocs pages: script: - mkdocs build - mv site public artifacts: paths: - public only: - master
3. mkdocs.yml
を配置
MkDocsの設定ファイルであるmkdocs.yml
を配置します。
site_name: "Title"
MkDocsの設定関連の記述はここに追加していくことになります。
4. masterにマージ
この状態で一度GitLab-CIに働いていただくためにmasterブランチにマージします。
5. docs/
以下にMarkdownファイルを配置
MkDocsの仕様としてdocs/
以下のMarkdownファイルを静的ページへと変換するので、管理したいドキュメントをdocs/
以下に配置します。このときdocs/
直下にindex.md
というファイルを置くことでindex.md
をトップページとして表示してくれるようになります。
完成
以上で完成です。これ以降masterブランチdocs/
以下のディレクトリ構造に則った静的ページを自動生成してくれます。反映されるページのURLはGitLabリポジトリの Settings > Pages で確認できます。
出来上がるページは以下のような感じです。
ついでに
上記だけでも静的ページは完成するのですが、さらに拡張機能を追加したりmkdocs.yml
を記述していくことでもっとオシャレな感じにも仕上げることができます。
.gitlab-ci.yml
image: python:3.7 before_script: - pip install --upgrade pip - pip install --upgrade mkdocs - pip install mkdocs-material - pip install pygments pages: script: - mkdocs build - mv site public artifacts: paths: - public only: - master
mkdocs.yml
site_name: "Title" theme: name: 'material' language: 'ja' palette: primary: 'cyan' accent: 'pink' feature: tabs: true logo: 'images/logo_long.png' extra: search: language: 'jp' markdown_extensions: - admonition - codehilite
このような簡単な設定だけでも以下のようにページの雰囲気がガラッと変わるので楽しいです。
まとめ
MkDocs + GitLabでのドキュメント管理による良し悪しは以下のような感じかなと思います。
メリット
- Markdown記法でお手軽編集
- ドキュメントやページの整理整頓が簡単
- Gitと連携しているためチームで管理しやすい
- ファイル操作を誤ってもGitの過去ログに残るので安心
- だれがいつ書いたものか調べられる
デメリット
- Confluenceからは疎遠になっていく
導入も複雑じゃない上に管理もしやすいため、一度環境を構築してしまえば特にデメリットらしいデメリットもないのではないかと思っています。Confluenceとはもっと共存していきたい次第です。押忍。
おわりに
正直なところ、MkDocsにこだわらずともドキュメントの管理は可能ですので各チームに合った形で管理できれば特に問題はないかと思います。
しかし僕のチームでは MkDocs + GitLab での管理を始めたことで明らかにメンバー全員のドキュメントに対する精神的ハードルが下がり、結果的に多くの情報が形として残り始めています。
個人的にはドキュメントも立派な会社の、プロダクトの、チームの資産だと思っているので、様々なドキュメント管理方法の一例として今回は MkDocs + GitLab を紹介させていただきました。
ぜひ参考にしてみてください!
次は久保田さんの記事です。
http://blog.engineer.adways.net/entry/advent_calendar_2018/15