Sphinx

Sphinx ↗ は、ドキュメントを簡単に作成するためのツールで、もともとはPythonのドキュメントの公開のために作られました。そのシンプルさと使いやすさで知られています。

このガイドでは、新しいSphinxプロジェクトを作成し、Cloudflare Pagesを使用してデプロイします。

前提条件

• Python 3 - SphinxはPythonに基づいているため、Pythonがインストールされている必要があります。

• pip ↗ - PythonパッケージをインストールするためのPyPA推奨ツール

• pipenv ↗ - プロジェクトのために自動的に仮想環境を作成し管理します。

ノート

すでにPython 3.7のバージョンを実行している場合は、このガイドを始める前に、コンピュータにPython 3.7がインストールされていることを確認してください。Python 3.7はCloudflare Pagesでサポートされている最新のバージョンです。

Python 3.7の最新バージョンは3.7.11です：

Python 3.7.11 ↗

Pythonのインストール

インストールガイダンスについては、公式のPythonドキュメントを参照してください：

• Windows ↗
• Linux/UNIX ↗
• macOS ↗
• Other ↗

Pipenvのインストール

Python 3.7をインストールする前に以前のバージョンのPythonがインストールされていた場合、他のグローバルパッケージがPipenvのインストールや、グローバルパッケージに依存する他のPythonプロジェクトの手順に干渉する可能性があります。

Pipenv ↗は、仮想環境の管理を簡単にするPythonベースのパッケージマネージャーです。このガイドでは、Sphinxサイトのデプロイを完了するためにPipenvの事前経験や知識は必要ありません。Cloudflare PagesはPipenvの使用をネイティブにサポートしており、デフォルトで最新バージョンがインストールされています。

Pipenvをインストールする最も簡単な方法は、次のコマンドを実行することです：

pip install --user pipenv

このコマンドは、Pipenvをユーザーレベルのディレクトリにインストールし、ターミナルからアクセスできるようにします。次のコマンドを実行して、期待される出力を確認できます：

pipenv --version

pipenv, version 2021.5.29

Sphinxプロジェクトディレクトリの作成

ターミナルから、次のコマンドを実行して新しいディレクトリを作成し、そこに移動します：

mkdir my-wonderful-new-sphinx-project
cd my-wonderful-new-sphinx-project

Python 3.7を使用したPipenv

Pipenvを使用すると、仮想環境に関連付けるPythonのバージョンを指定できます。このガイドの目的のために、Sphinxプロジェクトの仮想環境はPython 3.7を使用する必要があります。

次のコマンドを使用します：

pipenv --python 3.7

次の出力が表示されるはずです：

Creating a virtualenv for this project...
Pipfile: /home/ubuntu/my-wonderful-new-sphinx-project/Pipfile
Using /usr/bin/python3.7m (3.7.11) to create virtualenv...
⠸ Creating virtual environment...created virtual environment CPython3.7.11.final.0-64 in 1598ms
  creator CPython3Posix(dest=/home/ubuntu/.local/share/virtualenvs/my-wonderful-new-sphinx-project-Y2HfWoOr, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/home/ubuntu/.local/share/virtualenv)
    added seed packages: pip==21.1.3, setuptools==57.1.0, wheel==0.36.2
  activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator,XonshActivator

✔ Successfully created virtual environment!
Virtualenv location: /home/ubuntu/.local/share/virtualenvs/my-wonderful-new-sphinx-project-Y2HfWoOr
Creating a Pipfile for this project...

ディレクトリの内容をリストします：

ls

Pipfile

Sphinxのインストール

Sphinxをインストールする前に、プロジェクトを格納するディレクトリを作成します。

ターミナルから、次のコマンドを実行してSphinxをインストールします：

pipenv install sphinx

次のような出力が表示されるはずです：

Installing sphinx...
Adding sphinx to Pipfile's [packages]...
✔ Installation Succeeded
Pipfile.lock not found, creating...
Locking [dev-packages] dependencies...
Locking [packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Updated Pipfile.lock (763aa3)!
Installing dependencies from Pipfile.lock (763aa3)...
  🐍   ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 0/0 — 00:00:00
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.

これにより、Pipenvによって管理される新しい仮想環境にSphinxがインストールされます。次のようなディレクトリ構造が表示されるはずです：

my-wonderful-new-sphinx-project
|--Pipfile
|--Pipfile.lock

新しいプロジェクトの作成

Sphinxがインストールされたので、quickstartコマンドを実行してテンプレートプロジェクトを作成できます。このコマンドは、前のステップで作成したPipenv環境内でのみ機能します。その環境に入るには、ターミナルから次のコマンドを実行します：

pipenv shell

Launching subshell in virtual environment...
ubuntu@sphinx-demo:~/my-wonderful-new-sphinx-project$  . /home/ubuntu/.local/share/virtualenvs/my-wonderful-new-sphinx-project-Y2HfWoOr/bin/activate

次のコマンドを実行します：

sphinx-quickstart

いくつかの質問が表示されるので、次のように回答してください：

Separate source and build directories (y/n) [n]: Y
Project name: <あなたのプロジェクト名>
Author name(s): <あなたの名前>
Project release []: <ここでデフォルトを受け入れるか、バージョンを提供できます>
Project language [en]: <ここでenを受け入れるか、地域の言語コードを提供できます>

これにより、アクティブなディレクトリに4つの新しいファイルが作成されます：source/conf.py、index.rst、Makefile、およびmake.bat：

my-wonderful-new-sphinx-project
|--Pipfile
|--Pipfile.lock
|--source
|----_static
|----_templates
|----conf.py
|----index.rst
|--Makefile
|--make.bat

これで、Cloudflare Pagesにサイトをデプロイするために必要なすべてが揃いました。Sphinxを使用してドキュメントを作成する方法については、公式のSphinxドキュメント ↗を参照してください。

Before you continue

All of the framework guides assume you already have a fundamental understanding of Git ↗. If you are new to Git, refer to this summarized Git handbook ↗ on how to set up Git on your local machine.

If you clone with SSH, you must generate SSH keys ↗ on each computer you use to push or pull from GitHub.

Refer to the GitHub documentation ↗ and Git documentation ↗ for more information.

GitHubリポジトリの作成

pipenvシェルセッション内ではない別のターミナルウィンドウで、SSHキーによる認証が機能していることを確認します：

eval "$(ssh-agent)"
ssh-add -T ~/.ssh/id_rsa.pub
ssh -T git@github.com

The authenticity of host 'github.com (140.82.113.4)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com,140.82.113.4' (RSA) to the list of known hosts.
Hi yourgithubusername! You've successfully authenticated, but GitHub does not provide shell access.

新しいGitHubリポジトリを作成するには、repo.new ↗にアクセスします。リポジトリが設定されたら、ターミナルで次のコマンドを実行してアプリケーションをGitHubにプッシュします：

git init
git config user.name "あなたの名前"
git config user.email "username@domain.com"
git remote add origin git@github.com:yourgithubusername/githubrepo.git
git add .
git commit -m "初回コミット"
git branch -M main
git push -u origin main

Cloudflare Pagesでのデプロイ

サイトをPagesにデプロイするには：

1. Cloudflareダッシュボード ↗にログインし、アカウントを選択します。
2. アカウントホームで、Workers & Pages > アプリケーションを作成 > Pages > Gitに接続を選択します。
3. 作成した新しいGitHubリポジトリを選択し、ビルドとデプロイの設定セクションで、次の情報を提供します：

設定オプション	値
プロダクションブランチ	main
ビルドコマンド	make html
ビルドディレクトリ	build/html

設定の下に、PYTHON_VERSIONを指定するための環境変数を設定することを忘れないでください。

例えば：

変数名	値
PYTHON_VERSION	3.7

サイトの設定が完了したら、最初のデプロイを開始できます。Cloudflare PagesがPipenv、プロジェクトの依存関係をインストールし、デプロイ前にサイトをビルドするのを確認できます。

ノート

Cloudflare Pagesに最初のサイトをデプロイするための完全なガイドについては、始めるガイドを参照してください。

サイトをデプロイした後、*.pages.devのプロジェクト用のユニークなサブドメインが提供されます。Sphinxサイトに新しいコードをコミットするたびに、Cloudflare Pagesは自動的にプロジェクトを再ビルドし、デプロイします。

新しいプルリクエストでプレビューのデプロイにもアクセスできるようになり、変更が本番環境にデプロイされる前にサイトにどのように表示されるかをプレビューできます。

Learn more

By completing this guide, you have successfully deployed your Sphinx site to Cloudflare Pages. To get started with other frameworks, refer to the list of Framework guides.