Adways Advent Calendar 2018 14日目の記事です。

http://blog.engineer.adways.net/entry/advent_calendar_2018

こんにちは。2018年度新卒、二度めの登場、佐土原です。

早いのもので前回の記事からあっという間に３ヶ月が経ちました。実家の母がこれを見つけ一瞬で連絡が飛んできて驚いたことにも懐かしさを帯びはじめる歳月です。母ちゃん今回も書いてるぞ。

さて、今回のブログでは僕の所属するチームで導入し始めたMkDocs + GitLabでのドキュメント管理について書いていこうと思います。

導入の背景

僕の携わるプロダクトも息の長いサービスとなってきており、日常的に「あの話はどうなったんだっけ？」「たしかここはこうだったよね？」という会話も増えてきました。そこでチームとしてしっかりこれまで/これからの経過をドキュメントにまとめよう、という声が大きくなってきたのが発端です。

しかし当然過去にもこのような話が出たことはあり、「過去のドキュメント」と「これから作成するドキュメント」を管理する上で生じた問題がざっと以下のようなものでした。

過去のドキュメントが煩雑

いつ、だれが、なんのために書いたドキュメントが、どこにあるのかほとんど把握できていない状態でした。

既存管理ページのUIがつらい

過去のドキュメントはMarkdown記法で書いていたため、GitLabリポジトリWikiの項目に置いていました。ドキュメントの量が膨らみ、結果としてリンクだらけに。それでもMarkdownで書きたい。

Confluenceとの同期が難しい

弊社で導入されているConfluenceにまとめればいいじゃない、という話もありますが、すでに過去のドキュメントがMarkdownで残ってるので移し替えのコストが高そうでした。あとMarkdownで書きたい。

↓これまでの管理ページ f:id:AdwaysEngineerBlog:20181220104303p:plain

つまり

Markdownで書きたい。

Markdownこそ正義。なんとしてでも。

そこで注目したのがMkDocsでした。

MkDocsとは

www.mkdocs.org

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 で確認できます。

出来上がるページは以下のような感じです。

f:id:AdwaysEngineerBlog:20181220104439p:plain

ついでに

上記だけでも静的ページは完成するのですが、さらに拡張機能を追加したり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