Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Sphinx

最終更新 Markdown で表示Agent セットアップ

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

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

前提条件

  • Python 3 — Sphinx は Python ベースのため、Python が必要です

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

  • pipenv ↗ — プロジェクト用の virtualenv を自動で作成・管理します

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

Python 3.7.11 ↗

Python のインストール

インストール手順は、公式の Python ドキュメントを参照してください。

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.

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

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: <Your project name>
Author name(s): <You Author Name>
Project release []: <You can accept default here or provide a version>
Project language [en]: <You can accept en here or provide a regional language code>

これで、作業ディレクトリに source/conf.py、index.rst、Makefile、make.bat の 4 つの新しいファイルが作成されます。

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

Cloudflare Pages にサイトをデプロイする準備は整いました。Sphinx でドキュメントを作成する方法は、公式の Sphinx ドキュメント ↗ を参照してください。

続ける前に

すべてのフレームワークガイドは、Git ↗ の基本的な理解があることを前提としています。Git を初めて使う場合は、この Git ハンドブックの要約 ↗ で、ローカルマシンへの Git のセットアップ方法を確認してください。

SSH でクローンする場合は、GitHub に対して push または pull する各コンピューターで SSH キーを生成 ↗ する必要があります。

詳細は GitHub のドキュメント ↗ と Git のドキュメント ↗ を参照してください。

GitHub リポジトリの作成

pipenv shell セッション外の別のターミナルウィンドウで、SSH 鍵による認証が動作することを確認します。

eval "$(ssh-agent)"
ssh-add -T ~/.ssh/id_rsa.pub
ssh -T [email protected]

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.

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

git init
git config user.name "Your Name"
git config user.email "[email protected]"
git remote add origin [email protected]:yourgithubusername/githubrepo.git
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

Cloudflare Pages でデプロイする

サイトを Pages にデプロイするには、次の手順を実行します。

  1. Cloudflare ダッシュボードで Workers & Pages ページを開きます。

    Workers & Pages を開く ↗

  2. Create application を選びます。

  3. Pages タブを選びます。

  4. Import an existing Git repository を選びます。

  5. 作成した新しい GitHub リポジトリを選び、Begin setup を選びます。

  6. Set up builds and deployments セクションで、次の情報を入力します。

設定項目 値
本番ブランチ main
ビルドコマンド make html
ビルドディレクトリ build/html

設定の下で、PYTHON_VERSION を指定する環境変数を必ず設定します。

例:

変数名 値
PYTHON_VERSION 3.7

サイトの設定が終わったら、最初のデプロイを開始できます。Cloudflare Pages が Pipenv、プロジェクトの依存関係をインストールし、サイトをビルドしてからデプロイする様子が表示されます。

サイトをデプロイすると、プロジェクト専用の *.pages.dev サブドメインが割り当てられます。Sphinx サイトに新しいコードをコミットするたびに、Cloudflare Pages はプロジェクトを自動で再ビルドしてデプロイします。

新しいプルリクエストでは プレビューデプロイ も利用できるので、本番に出す前に変更後の見た目を確認できます。

さらに学ぶ

このガイドを完了すると、Sphinx サイトを Cloudflare Pages にデプロイできています。ほかのフレームワークを始めるには、Framework ガイドの一覧 を参照してください。

役に立ちましたか？