JavaScriptを有効にしてください

Cloudflare Pages上でSphinxサイトを自動デプロイする

 ·   8 min read

※記事内に商品プロモーションを含むことがあります。

はじめに

静的サイトホスティングサービスのCloudflare Pages上でドキュメント生成ツールSphinxを自動デプロイする手順を備忘録としてまとめました。

Sphinxのソースファイル(reSTやMarkdownなど)をGitHubにpushすると、Cloudflare Pagesでデプロイして、サイトを公開するようにします。
また、Cloudflare Pages上でのSphinxのデプロイには、Pipenv(Pythonのパッケージ管理ツール)で生成した環境設定ファイルPipfileが必要ですが、この記事では手動で作成しました。

主な手順は以下の通りです。

  1. Pipenvの導入(任意)
  2. Sphinxプロジェクトの作成
  3. Pipfileの作成
  4. GitHubへソースファイルをpush
  5. 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の使い方は以下のサイトを参考にしてください。

シェアする

Helve
WRITTEN BY
Helve
関西在住、電機メーカ勤務のエンジニア。X(旧Twitter)で新着記事を配信中です

サイト内検索