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

GitHub ActionsでSphinxドキュメントをビルドし、生成されたドキュメントをそのままS3へアップロードする実装のサンプルです。

#GitHub

#GitHub Actions

#Sphinx

#Amazon S3

#AWS

mochida.atsushi

2022.05.02

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

現在、自分は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）する

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

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と正しく入力された場合だけジョブが実行される）。

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

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