はじめに #
静的サイトホスティングサービスのCloudflare Pages上でドキュメント生成ツールSphinxを自動デプロイする手順を備忘録としてまとめました。
Sphinxのソースファイル（reSTやMarkdownなど）をGitHubにpushすると、Cloudflare Pagesでデプロイして、サイトを公開するようにします。
また、Cloudflare Pages上でのSphinxのデプロイには、Pipenv（Pythonのパッケージ管理ツール）で生成した環境設定ファイルPipfileが必要ですが、この記事では手動で作成しました。
主な手順は以下の通りです。
- Pipenvの導入（任意）
- Sphinxプロジェクトの作成
- Pipfileの作成
- GitHubへソースファイルをpush
- Cloudflare Pagesの設定
前提 #
PythonとSphinxは既にインストール済みで、Cloudflare PagesとGitHubのアカウントを既に作成しているものとします。検証したローカルの環境は以下の通りです。
- Windows 10
- Anaconda 2021.11
- Python v3.9.7
- Sphinx v4.2.0
Sphinxの詳細は以下の記事を参考にしてください。 Sphinxを使ったHTMLドキュメント作成 – Helve Tech Blog
Pipenvの導入 #
Sphinxプロジェクトを作成する前に、可能であればPythonのパッケージ管理ツールPipenvを導入します。これは、Cloudflare Pagesでデプロイするための環境をPipenvの環境設定ファイルPipfileで指定するためです。
また、Cloudflare Pagesで利用できるPythonのバージョンは2.7, 3.5, 3.7だけなので、PipenvではPython 3.7を導入します。ただし、今回使用したPCではAnacondaを使用しているため、Pipenvを導入せずに進めます。
Sphinxプロジェクトの作成 #
Sphinxプロジェクトを作成します。適当な空フォルダを作成し、PowerShellでsphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。
> sphinx-quickstart
作成中にいくつか設定がありますが、以下の設定にはyと回答して、ソースとビルドのディレクトリを分けます。
> Separate source and build directories (y/n) [n]: y
Sphinxプロジェクトの作成後、以下のコマンドを実行してbuild/htmlフォルダにhtmlファイルが生成されることを確認します。
> .\make.bat html
Pipfileの作成 #
Cloudflare Pages上でSphinxをデプロイするためには、PipfileというファイルでPythonやライブラリのバージョンを指定する必要があります。Pipfileは、Pipenv（Pythonのパッケージ管理ツール）で他のユーザと開発環境を共有するなどの目的で使用されています。
ここでは、以下のようなPipfileを手動で作成します（もちろん、可能であればPipenvを導入してPipfileを自動生成した方が望ましいです）。
[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true
[dev-packages]
[packages]
sphinx = "==4.2.0"
[requires]
python_version = "3.7"
[packages]以下に使用するライブラリを記述します（プラグインを使用する場合は追加します）。なお、ライブラリのバージョンを指定しない（最新バージョンを指定する）場合、*となります。
例：sphinx = "*"
SphinxプロジェクトのルートディレクトリにPipfileを置きます。
また、Cloudflare Pagesのリファレンスによると、PipfileだけでなくPipfile.locも必要なように読めますが、前者だけで問題なく自動デプロイできました。
GitHubへソースファイルをpush #
GitHub上に空のリポジトリを作成します。Privateリポジトリで問題ありません。
次に、SphinxプロジェクトをGitリポジトリにします。プロジェクトのルートディレクトリで以下を実行します（リモートリポジトリのURLは適宜変更してください）。
> git init
> git remote add origin https://github.com/AAA/BBB.git
buildフォルダ以外をGitのインデックスに追加します。
> git add source/ make.bat Makefile Pipfile
もしくは以下のような.gitignoreを作成して、buildフォルダを除外するのも良いと思います。
build/
GitHubにソースファイルをpushします。
> git commit -m "First commit"
> git push --set-upstream origin main
Cloudflare Pagesの設定 #
Cloudflare PagesでSphinxをビルドするように設定します。Cloudflare Pagesのページで「プロジェクトを作成」→「Gitに接続」と進みます。次に、リポジトリを選択して「セットアップの開始」をクリックします。 さらに「ビルドとデプロイのセットアップ」で以下の値を設定します。
- プロダクション ブランチ：
main - ビルド コマンド：
make html - ビルド出力ディレクトリ：
build/html
「環境変数 (アドバンスド)」にも以下を設定します。
- 変数名：
PYTHON_VERSION - 値：
3.7
設定後、「保存してデプロイする」を押すとデプロイが始まります。
デプロイの完了後、サイトのURLが表示されるので、アクセスするとSphinxのサイトが表示されます。
以降、ソースファイルを更新してGitHubのmainブランチにpushすると、Cloudflare Pages上で自動デプロイされます。
この記事はCloudflare Advent Calendar 2022の19日目の記事です。
参考 #
Pipenvの使い方は以下のサイトを参考にしてください。
