Environment setup

Prerequisites

The prerequisites for this workshop are having git and python installed (python3.12 is recommended), as well as having a GitHub account.

The tutorial focuses on UNIX-based systems, but we will providing some tips on how to run the commands on others.

You can choose to work on your own environment using any IDE, although there will be some extra tips provided for a local workflow using Visual Studio Code.

Creating your project

  1. To get started, create a new project using the example project Sphinxy as a template on GitHub Codespaces. This will open up a copy of Sphinxy on codespaces for you.

  2. From the source control tab on the left panel of Codespaces, select “Publish Branch”.

  3. You’ll be prompted to name your new remote repository, select the public option and name your repo sphinxy.

On your computer

  1. Create a new, public repository on your personal GitHub organisation from our template project, by clicking on the “Use this template => Create a new repository” button.

  2. Name your repo sphinxy.

  3. Clone your new repo locally:

    git clone git@github.com:<your-org>/sphinxy.git
cd sphinxy

Using a virtual environment

Next, we will be setting up a virtual environment, where later we will be installing everything else we need for the workshop.

python3.12 -m venv venv
source venv/bin/activate

Finally, we’ll install our package in edit mode. This will be needed later by some Sphinx extensions:

pip install -e .

If you are using a different OS and/or shell the command to activate your virtual environment might differ, so check the Platform | Shell | Command table in the docs.

In order to exit your virtual environment at any point, you can run:

deactivate


Previous: Home Next: Getting started with Sphinx