NTTドコモR&Dの技術ブログです。

トップ > クラウド > Google Cloud×Github Actions×MkDocsで開発ガイド作成

Google Cloud×Github Actions×MkDocsで開発ガイド作成

クラウド アドベントカレンダー2024 python

TL; DR

  • Streamlitを用いたWebアプリの基盤の開発・運用をしている。
  • 社内アプリ開発者用に用意しているMarkdownをGoogle CloudとGithub ActionsおよびMkDocsを使って開発ガイドとして公開した。

自己紹介

  • NTTドコモ データプラットフォーム部（以下DP部）黒須です。
  • 我々のチームではStreamlitを用いたWebアプリ基盤の開発・運用をしております。（以下の記事を参考）

nttdocomo-developers.jp

  • 社内アプリ開発者用に環境構築からアプリデプロイまでの実施方法をMarkdownでまとめており、MkDocsとCloud Runを使って開発ガイドとして公開しております。
  • 本記事ではフレームワーク選定、全体構成、MkDocsの設定について工夫した点をご紹介します。

1. フレームワーク選定

  • 社内アプリ開発者用のドキュメントはMarkdown形式でGithubで管理をしています。
  • また開発メンバーは普段Pythonを用いて開発をしております。
  • そのため、PythonベースでMarkdownから静的Webサイトを生成できる以下のフレームワークを比較しました。
比較項目 MkDocs Pelican Sphinx
学習コスト 低い (設定やカスタマイズが簡単) 中程度 (設定に多少の学習が必要) 高い (設定やカスタマイズに時間がかかる)
更新頻度 非常に活発 定期的 非常に活発

  • 実際にMkDocsを使用してみたところ、以下の利点が確認できたため、MkDocsを採用しました。

    • ymlファイルを編集することで設定を簡単に変更できる
    • ローカルで実行確認が容易
    • ビルドが高速

2. 全体構成

  • ドキュメントの提供の為に構築した環境は下図の通りです。
  • 資材はGitHub上で管理しており、GitHub Actionsを用いてCloud Runへのデプロイを行っています。

処理の大まかな流れは以下です。

  1. GitHubのブランチから変更をプッシュ
  2. 検証環境、本番環境ごとにGitHub Environmentの機能を使ってそれぞれの環境変数を設定
  3. Workload Identity機能を使ってGitHub Actions上でGoogle Cloudの認証
  4. Docker Imageのビルド
  5. Artifact RegistryにImageをプッシュ
  6. Cloud Runにデプロイ

2.1 GitHubのブランチから変更をプッシュ

  • コード管理をGitHubで行っており、Webアプリ基盤においても使用しているため、CI/CDのワークフローはGitHub Actionsを利用しました。
  • GitHubのホストランナーはメモリ7GB、ストレージ14GBの制限があるので、今後ドキュメントの量が増えても問題ないスペックです。

2.2 GitHubのEnvironmentの機能を利用した環境変数の設定

  • ブランチについては本番環境用のmainブランチ、開発環境用のdevブランチを運用しております。
  • 各環境ごとの設定はGitHub Environmentを使うことで簡単に実装できました。以下は各環境ごとにCloud Runで使用するサービスアカウントを設定する例になります。

GitHub Environment variables

Name Value Environment
CLOUDRUN_SERVICE_ACCOUNT 本番環境用のサービスアカウント main
CLOUDRUN_SERVICE_ACCOUNT 開発環境用のサービスアカウント dev

GitHub Actionsで利用するymlファイル

# 各環境で利用するCloud RunのサービスアカウントをGITHUB_ENVに保存
echo "CLOUDRUN_SERVICE_ACCOUNT=${{ secrets.CLOUDRUN_SERVICE_ACCOUNT }}" >> $GITHUB_ENV

2.3 Workload Identityを使った認証

  • Workload Identityを使用することで、GitHub ActionsからGoogle Cloudのリソースに安全かつ効率的にアクセスできます。
  • Workload IdentityのOIDCトークンを使用した動的な認証によりセキュリティが向上し、サービスアカウントキーの管理が不要になります。CI/CDパイプラインの構築も簡単になります。

2.4 Docker Imageのビルド

  • 工夫した点として2.4.1 ドキュメントのビルドとサーブ、2.4.2 Google Analyticsの設定の2点があります。

2.4.1 ドキュメントのビルドとサーブ

  • MkDocsには、以下2つの主要なコマンドがあります。

    • mkdocs build:
      • Markdownファイルから静的なHTMLファイルを生成し、指定されたディレクトリに出力します。
    • mkdocs serve:
      • ローカル開発サーバーを起動し、リアルタイムでドキュメントの変更をプレビューできます。

  • 開発時はmkdocs serveでプレビューを確認しながらドキュメントを編集しております。

  • デプロイ時にはmkdocs serveでサーブするのではなく、mkdocs buildコマンドを実行して静的なHTMLファイルを生成しNginxでページをサーブする構成にしています。Nginxは開発が盛んでパフォーマンスやセキュリティが安定しているため、この構成にしました。

Dockerfile

# mkdocsでドキュメントをビルド
RUN poetry run mkdocs build --clean

# 作業ディレクトリの移動
WORKDIR /

# Nginxのデフォルトのウェブページを削除
RUN rm /usr/share/nginx/html/*

# Docker内でファイルをコピーする
RUN cp -r /usr/src/document/site/* /usr/share/nginx/html

# フォアグランドでNginxを動かす
CMD ["nginx", "-g", "daemon off;"]

2.4.2 Google Analyticsの設定

  • 各環境でGoogle Analyticsの設定を変更する必要があるため、GitHub Environmentから環境ごとの設定を読み込み、Dockerfile内でmkdocs.ymlを書き換える処理を行っています。

GitHub Environment variables

Name Value Environment
GA4_TRACKING_ID 本番環境用のトラッキングID main
GA4_TRACKING_ID 開発環境用のトラッキングID dev

Dockerfile

# GA4のIDを引数として受け取る
ARG GA4_TRACKING_ID

# GA4のIDを書き換え
RUN sed -i "s/GA4_TRACKING_ID/${GA4_TRACKING_ID}/g" ./mkdocs.yml

2.5 Artifact RegistryにImageをプッシュ

  • Cloud Runにデプロイする前に、Artifact Registryにコンテナイメージを保管します。これにより、一貫性、再利用性、セキュリティ、バージョン管理、効率的なデプロイ等の利点があります。

2.6 Cloud Runにデプロイ

  • 環境ごとにリビジョンタグをつけてデプロイしています。Cloud Runにデプロイするたびにリビジョンが作成されます。
  • リビジョンタグをつけかえることで簡単にロールバックが可能です。

3. MkDocsの設定

  • MkDocsの設定で工夫した点は3点あります。mkdocs.ymlファイルを編集することで簡単に実施できます。

3.1 サイドバーの設定

  • サイドバーの構成を大項目、中項目、小項目に分類することで、どこに何が記載されているかをわかりやすくしました。
  • これによってユーザーが必要な情報を迅速に見つけることができるようになります。mkdocs.ymlのnavを編集することで、簡単に設定可能です。

mkdocs.yml

nav:
  - Guides - スタートアップガイド: # 大項目
    - 概要: # 中項目
        - 概要.md # 小項目
    - 開発: # 中項目
        - 申請.md # 小項目
        - 開発手順.md # 小項目

  - Manuals - マニュアル: # 大項目
    - 機能一覧: # 中項目
        - 機能1.md # 小項目
        - 機能2.md # 小項目

3.2 デザインの拡張

デフォルトのmaterialテーマでは見づらい箇所があったため、以下の拡張機能を利用することでより読みやすいドキュメントにしました。

  • 追加のCSSの適用
    • mkdocs.ymlのextra_cssを追記することで、追加のCSSパスを設定します。

mkdocs.yml

extra_css:
  - css/custom_material.css

  • これによってユーザー定義のCSSを適用できます。主に以下を変更しました。

    • ヘッダーのスタイル
    • サイドバーの文字色・背景色
    • テーブルの背景色

  • admonitionの適用

    • また、mkdocs.ymlのmarkdown_extensionsにadmonitionを追記することで、注意文（メモ、ヒント、警告など）を目立つスタイルで表示するようにしました。

mkdocs.yml

markdown_extensions:
  - admonition

3.1、3.2を適用した開発ガイドのサンプルがこちらになります。

3.3 日本語検索機能の導入

  • MkDocsでは複数のテーマが用意されていて、それぞれ機能が異なります。 当初はmaterialではなく、readthedocsというテーマの導入を検討していました。

  • 検索の機能面で比較した結果、最終的にmaterialテーマを利用することにしました。

テーマ名 日本語対応 検索単語のハイライト サジェスト
readthedocs 日本語と英語両方の検索に対応できない 設定項目なし 設定項目なし
material 日本語と英語の両方に対応する検索が可能 設定可能 設定可能
  • MkDocsではmkdocs.ymlのpluginsにsearchを追記することで検索機能を簡単に設定できます。

mkdocs.yml

plugins:
  search:
    lang: ja
  • materialテーマの検索機能にも課題はあります。 MkDocsの内部では、ビルド時にMarkdownファイルから検索用のIndexを作成しています。しかし内部で使用されている日本語を正しく分割する機能の性能が低いです。 公式のドキュメントでも周知されていますが、中国語のテキストを正確に分割するために利用されているjiebaを日本語や韓国語にも適用する予定があるとのことなので今後に期待しております。

あとがき

  • 本記事ではGoogle CloudとGithub ActionsとMkDocsを使ってMarkdownを開発ガイドとして公開する一連の流れをご紹介しました。
  • 今後、Google Analyticsの分析結果をもとに改善を行っていきます。
  • 本記事については業務委託先メンバーである、藤井さん・井出さんに執筆協力いただきました。この場を借りて感謝申し上げます。