はじめに

社内でmkdocsを用いたドキュメント作成を行っていて、markdownベースで書きやすそうと思ったので実際に使ってみることにしました。

この記事では、GitHub Actionsを用いたドキュメントの作成からGitHub pagesでの公開までの自動化も含めて、mkdocsとGitHub Actionsについてまとめています。

mkdocsとは?

MarkdownファイルをHTMLに変換する静的サイトジェネレーターです。
ユーザーはMarkdown形式でサイトの内容を記載した上で、mkdocsコマンドを利用することでドキュメントの作成・確認などを行うことが可能です。

www.mkdocs.org

また、テーマも選択することができるので、好きなデザイン (e.g. Gitbook etc.) を利用したドキュメントを作成することができます。
github.com

GitHub Actionsとは?

ソフトウェア開発で利用できるワークフローの自動化ツール(CI/CDツール)の一つです。
(Travis CI, Circle CIなどの類似サービスと考えていただければいいと思います。)

github.co.jp

ユーザーは.github/workflowsディレクトリ内にワークフローの定義ファイルを作成して配置することで、自動的に実行してくれます。

また、自身で作成したワークフローに定義済みの処理であるActionsを組み込むことも可能です。今回は下記の2つのActionsを利用します。

peaceiris/actions-gh-pages: 静的ファイルのGitHub PagesへのDeploy
8398a7/action-slack: Slackへの通知

github.com
github.com

実装

ワークフローの定義ファイルなどは下記のrepositoryで公開しています。

github.com

自分が定義したワークフローでは、下記のようなフローでドキュメントの公開まで行います。

ユーザーがMaster以外のブランチでDocumentを修正して、Pull Request(PR)を作成する
レビュー後にPRをMaster BranchにMergeして、それをトリガーとしてワークフローのjobが起動する
静的ファイルからドキュメントのbuildを行う (mkdocs build)
buildしたドキュメントをGitHub Pagesで公開する(peaceiris/actions-gh-pages)
GitHub Actionsの結果をSlackで通知する(8398a7/action-slack)

ドキュメントのテーマはMaterialを利用しました。

squidfunk.github.io

mkdocsの定義

repositoryのdocsディレクトリに作成したドキュメント(Markdownファイル)を配置します。
docsディレクトリの下で作成したフォルダごとにファイルをまとめることも可能です。

docsディレクトリ内のファイルはmkdocs.yml内のnav:の部分で設定します。
タブ機能を有効化しているので、nav:の直下に記載されているHome:などの項目がタブとして表示されています。
さらに、<ドキュメントの名前>:<ドキュメントのファイルパス>の形式で指定して、タブの項目に紐づける形でドキュメントをまとめます。

Hint:の部分のように、階層的にドキュメントをまとめることも可能です。

site_name: taxin-pages
theme:
  name: material
  language: ja
  features:
    - tabs
  palette:
    primary: indigo
    accent: indigo
markdown_extensions:
  - codehilite
  - footnotes
  - meta
  - admonition
  - plantuml_markdown:
      server: http://www.planturl.com/planturl
extra:
  search:
    language: 'ja'
plugins:
  - git-revision-date-localized
nav:
  - Home:
    - Top: index.md
    - Hint:
      - plantUML: about/hint-plantuml.md
    - Build configuration: about/document-build.md
  - Guides:
    - architecture: design/architecture.md

上記の設定でドキュメントの画面は下記のようになります。
Home, Guidesというタブが作成されて、それらのタブに紐付く形でドキュメントがまとめられていることがわかります。
f:id:taxintt:20200607104651p:plain

注意点としてホーム画面としてのindex.mdが必須になるため、index.mdは作成してディレクトリのトップレベルに配置しておきましょう。
index.mdが存在しない場合、ドキュメントのbuild自体が正常に完了しても作成されたドキュメントの表示が崩れることがあります。

www.mkdocs.org

ワークフローの定義

先述した通り、PRのMergeをトリガーとしてワークフローのjobが起動するようにon:の部分で設定しています。
mkdocsなど必要なパッケージをダウンロードして、ドキュメントのbuildとdeployを行います。

buildの際には、--cleanのオプションを指定してbuild時に作成されるsiteディレクトリ配下のファイルを毎回削除してから、ドキュメントをbuildします。
ドキュメントを複数回作成する際に、不要なファイル類が紛れ込まないようにするために必要なオプションとなります。

www.mkdocs.org

name: Deploy mkdocs

on:
  pull_request:
    # masterへのPRをトリガーとして実行する
    branches:
      - master
    types:
      - closed

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - name: checkout branch 
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: configure git info
        run: |
          git config --global user.name "github-actions-for-deploy"
          git config --global user.email deploy-actions@github.com

      - name: check git status and branch
        run: |
          git status
          git branch

      # mkdocsを利用するためのpython環境のsetupを行う
      - name: setup python env
        uses: actions/setup-python@v1
        with:
          python-version: '3.8'

      - name: install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: mkdocs build
        run: |
           mkdocs build --verbose --clean --strict

      - name: mkdocs deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
           github_token: ${{ secrets.PERSONAL_TOKEN }}
           publish_dir: site
           
      - name: notify slack
        uses: 8398a7/action-slack@v3
        if: always()
        with:
          status: ${{ job.status }}
          fields: repo,message,commit,author,action,eventName,ref,workflow  
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}