Deploy a Sphinx site
In this guide you'll create a new Sphinx project and deploy it using Cloudflare Pages.
There are a few prerequisites before you can begin creating your Sphinx site, namely you'll need to install it!
Sphinx is a Python based tool, which means you'll need to have Python installed to make use of it. We recommend installing Python version 3.7 as this is the latest version at the time of writing Cloudflare Pages supports. Please refer to the official Python docs on installing for your platform at their relevant pages:
Wonderful, by now you should have Python installed. If you already had Python installed, please be mindful that any other global packages you may have installed could interfere with the following steps to install Pipenv, or your other Python projects which depend on global packages!
is a Python based package manager that makes managing virtual environments super simple. If you're not familiar with it yet, don't worry, it's easy to pick up. Cloudflare Pages natively supports the use of Pipenv and by default has the latest version installed.
The quickest way to install Pipenv is by running the command:
$ pip install --user pipenv
This will install Pipenv to your user level directory and will make it accessible via your terminal. You can confirm this by running the following command and seeing the expected output:
$ pipenv --versionpipenv, version 2020.11.15
Just one last step before can install Sphinx, we first have to create the directory we want our project to live in. From your terminal run the following commands to create a new directory and navigate within it:
$ mkdir my-wonderful-new-sphinx-project$ cd my-wonderful-new-sphinx-project
We're finally ready to install Sphinx. From your terminal run the following command to install Sphinx:
$ pipenv install sphinx
This will install sphinx into a new virtual environment managed by Pipenv, you should see a directory structure like this:
Creating a new project
With Sphinx installed you can now run the quickstart command to create a template project for you. This command will only work within the Pipenv environment we created in the previous step. To enter that environment run the following command from your terminal:
$ pipenv shell
Now run the following command:
You will be presented with a number of questions, please answer them in the following:
$ 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>
This will create four new files in your active directory,
Creating a GitHub repository
$ git remote add origin https://github.com/yourgithubusername/githubrepo$ git add . && git commit -m "Initial commit"$ git branch -M main$ git push -u origin main
Deploying with Cloudflare Pages
You can deploy your site to Cloudflare Pages by going to the dashboard, and creating a new site. Select your new GitHub repository that you created above, and in the configuration section, provide the following information:
Below the configuration, make sure to set the environment variable for specifying the
Once you've configured your site, you can begin your first deploy. You should see Cloudflare Pages installing
your project dependencies, and building your site, before deploying it.
Once you've deployed your site, you'll receive a unique subdomain for your project on
pages.dev. Every time you commit
new code to your Hugo site, Cloudflare Pages will automatically rebuild your project and deploy it. You'll also get
access to on new pull requests, so you can preview how changes look
to your site before deploying them to production.