← Cloudflare Pages / pages / framework-guides

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:

• Windows ↗
• Linux/UNIX ↗
• macOS ↗
• Прочее ↗

Если до установки версии 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

В терминале выполните следующие команды, чтобы создать новый каталог и перейти в него:

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

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:

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:

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, необходимо сгенерировать ключи SSH ↗ на каждом компьютере, с которого вы отправляете или получаете данные из GitHub.

См. документация GitHub ↗ и Документация Git ↗, где это описано подробнее.

В отдельном окне терминала вне сессии 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.

Создайте новый репозиторий GitHub, перейдя по адресу repo.new ↗. После настройки репозитория отправьте приложение в 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

Чтобы развернуть сайт в Pages:

1. На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

   Перейдите в Workers & Pages ↗

2. Выберите Создать приложение.

3. Выберите Pages на вкладке.

4. Выберите Импорт существующего репозитория Git.

5. Выберите созданный вами новый репозиторий GitHub, а затем нажмите Начало настройки.

6. В Настройка сборок и деплоев раздел и укажите следующую информацию:

После этой конфигурации обязательно задайте переменную окружения, указывающую PYTHON_VERSION.

Например:

После настройки сайта вы можете запустить первый деплой. Вы увидите, как Cloudflare Pages устанавливает Pipenv, зависимостей вашего проекта и сборку сайта перед развертыванием.

После деплоя сайта вы получите уникальный поддомен для своего проекта на *.pages.dev. Каждый раз, когда вы фиксируете новый код на сайте Sphinx, Cloudflare Pages автоматически пересоберет ваш проект и развернет его.

Также вы получите доступ к развёртывания предпросмотра для новых pull request, чтобы вы могли увидеть, как изменения выглядят на сайте, прежде чем разворачивать их в продакшен.

После выполнения этого руководства вы успешно развернули свой сайт на Sphinx на Cloudflare Pages. Чтобы начать работу с другими фреймворками, обратитесь к списку руководств по фреймворкам.