← Cloudflare Pages / pages / framework-guides

Sphinx

Sphinx ↗ je nástroj, který usnadňuje tvorbu dokumentace a původně vznikl pro publikování dokumentace k Pythonu. Je známý svou jednoduchostí a snadným používáním.

V tomto průvodci vytvoříte nový projekt Sphinx a nasadíte ho pomocí Cloudflare Pages.

Předpoklady

Python 3 - Sphinx je založený na Pythonu, proto musíte mít nainstalovaný Python
pip ↗ - nástroj doporučený PyPA pro instalaci balíčků Python
pipenv ↗ - automaticky vytváří a spravuje virtualenv pro vaše projekty

Nejnovější verzí Python 3.7 je 3.7.11:

Python 3.7.11 ↗

Instalace Pythonu

Pokyny k instalaci najdete v oficiální dokumentaci Pythonu:

Instalace Pipenv

Pokud jste před instalací verze 3.7 měli nainstalovanou starší verzi Pythonu, mohou nainstalované globální balíčky ovlivnit následující kroky při instalaci Pipenv nebo vaše další projekty v Pythonu, které na globálních balíčcích závisí.

Pipenv ↗ je správce balíčků založený na Pythonu, který zjednodušuje správu virtuálních prostředí. Pro dokončení nasazení webu Sphinx podle tohoto návodu nepotřebujete žádné předchozí zkušenosti ani znalosti Pipenv. Cloudflare Pages nativně podporuje použití Pipenv a má ve výchozím nastavení nainstalovanou nejnovější verzi.

Nejrychlejší způsob instalace Pipenv je spuštění příkazu:

pip install --user pipenv

Tento příkaz nainstaluje Pipenv do vašeho uživatelského adresáře a zpřístupní ho v terminálu. Ověřit to můžete spuštěním následujícího příkazu a porovnáním s očekávaným výstupem:

pipenv --version

pipenv, version 2021.5.29

Vytvoření adresáře projektu Sphinx

V terminálu spusťte následující příkazy pro vytvoření nového adresáře a přechod do něj:

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

Pipenv s Pythonem 3.7

Pipenv umožňuje určit, kterou verzi Pythonu chcete s virtuálním prostředím spojit. Pro účely tohoto návodu musí virtuální prostředí vašeho projektu Sphinx používat Python 3.7.

Použijte následující příkaz:

pipenv --python 3.7

Měl by se zobrazit následující výstup:

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...

Vypište obsah adresáře:

ls

Pipfile

Instalace Sphinx

Než nainstalujete Sphinx, vytvořte adresář, ve kterém chcete mít svůj projekt.

V terminálu spusťte následující příkaz pro instalaci Sphinx:

pipenv install sphinx

Měl by se zobrazit výstup podobný tomuto:

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.

Tím se Sphinx nainstaluje do nového virtuálního prostředí spravovaného Pipenv. Měli byste vidět strukturu adresářů podobnou této:

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

Vytvoření nového projektu

Po nainstalování Sphinx můžete nyní spustit příkaz quickstart, který za vás vytvoří šablonu projektu. Tento příkaz bude fungovat pouze v prostředí Pipenv, které jste vytvořili v předchozím kroku. Pro vstup do tohoto prostředí spusťte v terminálu následující příkaz:

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

Nyní spusťte následující příkaz:

sphinx-quickstart

Zobrazí se vám řada otázek, na které odpovězte následovně:

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>

Tím se ve vašem aktivním adresáři vytvoří čtyři nové soubory, source/conf.py, index.rst, Makefile a make.bat:

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

Nyní máte vše potřebné k nasazení webu na Cloudflare Pages. Chcete-li se naučit vytvářet dokumentaci pomocí Sphinx, přečtěte si oficiální Dokumentace Sphinx ↗.

Než budete pokračovat

Všechny průvodce frameworky předpokládají, že již máte základní znalosti Git ↗. Pokud s Gitem začínáte, podívejte se na tento shrnutá příručka ke Gitu ↗ jak nastavit Git na svém lokálním počítači.

Pokud klonujete přes SSH, musíte vygenerujte SSH klíče ↗ na každém počítači, který používáte pro push nebo pull z GitHubu.

Viz dokumentace GitHub ↗ a Dokumentace Git ↗ s dalšími informacemi.

Vytvoření repozitáře GitHub

V samostatném okně terminálu, které není součástí relace pipenv shell, ověřte, že funguje ověřování pomocí SSH klíče:

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.

Vytvořte nový repozitář GitHub na repo.new ↗. Jakmile je repozitář nastavený, v terminálu spusťte následující příkazy, kterými odešlete svou aplikaci na 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

Nasadit pomocí Cloudflare Pages

Chcete-li nasadit svůj web do Pages:

V dashboardu Cloudflare přejděte na Workers & Pages stránce.
Přejděte na Workers & Pages ↗
Vyberte Vytvoření aplikace.
Vyberte Pages kartě.
Vyberte Importujte existující repozitář Git.
Vyberte nově vytvořený repozitář GitHub a poté vyberte Zahájit nastavení.
V Nastavení sestavení a nasazení sekci uveďte následující informace:

Konfigurační možnost	Hodnota
Produkční větev	`main`
Příkaz sestavení	`make html`
Adresář sestavení	`build/html`

Pod konfigurací nezapomeňte nastavit proměnnou prostředí pro určení PYTHON_VERSION.

Například:

Název proměnné	Hodnota
PYTHON_VERSION	3.7

Po nakonfigurování webu můžete spustit první nasazení. Měli byste vidět, jak Cloudflare Pages instaluje Pipenv, závislosti projektu a sestavuje web před nasazením.

Po nasazení webu získáte pro svůj projekt jedinečnou subdoménu na *.pages.dev. Pokaždé, když do svého webu Sphinx committnete nový kód, Cloudflare Pages automaticky znovu sestaví váš projekt a nasadí ho.

Získáte také přístup k náhledová nasazení u nových pull requestů, takže si můžete prohlédnout, jak změny na vašem webu vypadají, než je nasadíte do produkce.

Zjistit více

Dokončením tohoto návodu jste úspěšně nasadili svůj web Sphinx na Cloudflare Pages. Chcete-li začít s dalšími frameworky, podívejte se na seznam návodů pro frameworky.