GitHub ActionsワークフローでSphinxドキュメントをS3へデプロイする

現在、自分はProfllyというプロフィールビューアーサービスの開発を行っています。

Profllyでは、ユーザー向けのドキュメント作成ツールとしてSphinxを利用しており、Sphinxでビルドされたユーザーマニュアル（HTMLファイル群）をS3（+CloudFront）に配置して公開するような形としています。

• Proflly GA ドキュメント

最近、これらユーザーマニュアルのビルド&デプロイ作業をGitHub Actionsを使って一部省力化したので、その実装サンプルをご紹介します。

なお、今回作成したサンプルはGitHubに公開しています。
https://github.com/amotz/sphinx-s3-actions-sample

Sphinxについて

Sphinxは、Pythonで書かれたドキュメンテーションツールです。
reStructuredText記法で書かれたテキストファイル（.rst）を、HTML/LaTeX/ePubなど様々な形式のファイルに出力することができます。

Sphinxは元々Pythonのドキュメンテーション用に開発されたもので、それ以外でも様々なプロジェクトで利用されています。
参考までに、以下のようなプロジェクトでSphinxが利用されているようです。

Sphinx Documentation - Sphinxを使用しているプロジェクト

サンプルイメージ

今回の実装サンプルでは、GitHub Actionsのワークフロー内でSphinxでビルドを実行しドキュメント（HTML群）を生成します。
さらに、生成されたファイルをドキュメントの配置場所に指定されているS3バケットにアップロードします。

Sphinxソースの準備

GitHub Actionsを構築する前には、まずはデプロイ対象となるSphinxのソースを準備しておきます。
詳細は割愛しますが、以下を参考にSphinxが動作する環境を準備しておきます。

Sphinx Documentation - Sphinxのインストール

今回は、とりあえず適当に sphinx-quickstart でソース一式を準備しました。

Sphinx Documentation - sphinx-quickstart

$ sphinx-quickstart

$ tree
.
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

念の為、手元の環境でもmakeしてSphinxが問題なくビルドできることを確認しておきましょう。

$ make html

GitHub Actionsの実装

デプロイ対象となるソースが準備できたので、Sphinxのビルド&デプロイを行うGitHub Actionのワークフローを実装してみます。

• 任意のタイミングでデプロイしたいので、トリガーは手動実行とする（workflow dispatch）
• リポジトリにはSphinxソースのみpushされているため、ワークフロー内でSphinxのビルドを行う
• ビルドで生成されたドキュメントファイル群を、ドキュメント配置場所となるS3バケットへアップロード（sync）する

これらの要件を元に実装した結果、ワークフローは以下のようになりました。

.github/workflows/deploy-docs.yml

name: "Deploy document files to S3"
on:
  workflow_dispatch:
    inputs:
      confirm:
        required: true
        description: Please type "deploy-docs".
env:
  AWS_REGION : "ap-northeast-1"
  ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}
  S3_BUCKET: ${{ secrets.S3_BUCKET }}
permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    if: github.event.inputs.confirm == 'deploy-docs'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Configure aws credentials
      uses: aws-actions/configure-aws-credentials@v1
      with:
        role-to-assume: ${{ env.ROLE_ARN }}
        role-session-name: actions-role-session
        aws-region: ${{ env.AWS_REGION }}

    - name: Setup Python
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"
        architecture: x64

    - name: Install sphinx
      run: |
        pip install -U sphinx

    - name: Build html
      run: |
        cd docs && make html

    - name: Sync html to s3
      run: |
        aws s3 sync docs/build/html s3://${{ env.S3_BUCKET }}/docs --delete --quiet

手動でイベントを実行したいのでトリガーは workflow dispatch としていますが、誤デプロイ防止に確認用のtypeフィールドを設けています（deploy-docsと正しく入力された場合だけジョブが実行される）。

• GitHub Docs - Workflow Syntax
• 【Developers.IO】 workflow_dispatchの誤実行防止策にinputsでの絞りを試してみた

また、AWSアカウントへのアクセスはOIDCプロバイダを介したIAM Roleを利用しています。

• GitHub Docs - Configuring OpenID Connect in Amazon Web Services
• 【Developers.IO】 GitHub Actions OIDCでconfigure-aws-credentialsでAssumeRoleする

今回はサンプルリポジトリをpublicにしているため、RoleのARNやS3バケットはGitHub Secretsに格納しています。

Workflow Dispatchによるデプロイ

ワークフローが構築できたので、実際にビルド&デプロイをやってみます。

対象リポジトリのActionsタブを開き、今回構築した Deploy document files to S3 を選択します。
次に、Run Workflow を選択して手動でワークフローを実行してみます。

誤操作防止のために仕込んだtypeフィールドに指定された文字を入力し、 Run Workflow ボタンをクリック。

ワークフローが実行され、ジョブが走り出しました。

しばらく待つと、無事にジョブが成功しています。

配置先のS3バケットを覗いてみると・・無事にビルドされたドキュメントファイル群がアップロードされています！

おわりに

Sphinxで定義されたユーザーマニュアルをビルドし、配信先であるS3へアップロードするGitHub Actionsを構築してみました。
今回は手作業でやっているSphinxのビルド&デプロイ処理を半自動化しただけでしたが、トリガーや設定をさらに見直してもう少し自動化を進めたいところです。

どなたかの参考になれば幸いです。

参考

• Sphinxのイケてるドキュメントを自動デプロイしてS3で公開する！