Sphinx

Sphinx ↗ 是一个轻松创建文档的工具，最初用于发布 Python 文档。它以简单和易用而闻名。

在本指南中，你将创建新的 Sphinx 项目并使用 Cloudflare Pages 部署。

前提条件

Python 3 - Sphinx 基于 Python，因此必须安装 Python
pip ↗ - PyPA 推荐的 Python 包安装工具
pipenv ↗ - 自动为项目创建和管理 virtualenv

Python 3.7 的最新版本是 3.7.11：

Python 3.7.11 ↗

安装 Python

请参阅官方 Python 文档获取安装指导：

安装 Pipenv

若在安装 3.7 版本之前已安装较早版本的 Python，你可能已安装的其他全局包可能干扰以下安装 Pipenv 的步骤，或依赖全局包的其他 Python 项目。

Pipenv ↗ 是基于 Python 的包管理器，简化了 virtualenv 的管理。本指南不要求你具备 Pipenv 经验或知识即可完成 Sphinx 站点部署。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

将 Pipenv 与 Python 3.7 配合使用

Pipenv 允许你指定 virtualenv 关联的 Python 版本。就本指南而言，Sphinx 项目的 virtualenv 必须使用 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 管理的新 virtualenv 中。你应看到如下目录结构：

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：

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 推送或拉取的计算机上生成 SSH 密钥 ↗。

更多信息请参阅 GitHub 文档 ↗和 Git 文档 ↗。

创建 GitHub 仓库

在未处于 pipenv shell 会话的单独终端窗口中，验证基于 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.

访问 repo.new ↗ 创建新的 GitHub 仓库。设置仓库后，在终端运行以下命令将应用推送到 GitHub：

git init
git config user.name "Your Name"
git config user.email "username@domain.com"
git remote add origin git@github.com:yourgithubusername/githubrepo.git
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

使用 Cloudflare Pages 部署

要将站点部署到 Pages：

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。
Go to Workers & Pages ↗
选择 Create application（创建应用程序）。
选择 Pages 选项卡。
选择 Import an existing Git repository（导入现有 Git 仓库）。
选择你创建的新 GitHub 仓库，然后选择 Begin setup（开始设置）。
在 Set up builds and deployments（设置构建和部署） 部分，提供以下信息：

配置选项	值
Production branch	`main`
Build command	`make html`
Build directory	`build/html`

在配置下方，确保设置用于指定 PYTHON_VERSION 的环境变量。

例如：

Variable name	Value
PYTHON_VERSION	3.7

配置站点后，即可开始首次部署。你将看到 Cloudflare Pages 安装 Pipenv、项目依赖并构建站点，然后完成部署。

部署站点后，你将在 *.pages.dev 上获得项目的唯一子域名。每次向 Sphinx 站点提交新代码时，Cloudflare Pages 都会自动重新构建并部署项目。

你还可以在新 pull request 上获得预览部署，在部署到生产环境之前预览更改效果。

了解更多

完成本指南后，你已成功将 Sphinx 站点部署到 Cloudflare Pages。要开始使用其他框架，请参阅框架指南列表。