Setting Up for Local Development

This page only covers the basic setup to enable local development of the welcome guide. Building the documentation is covered elsewhere.

Installing Prerequisites

1. Install Python 3.10 or greater.

2. (Optional) Install Hatch. Handles environment management and provides some handy command-line functions to simplify documentation building.

3. (Optional) Install Pandoc. Only required to build the PDF version of the guide.

Getting the Source Files

1. Create your own fork of the Welcome Guide (look for the "Fork" button on GitHub).

2. Clone your fork.

   with ssh (requires that your ssh key is added to your GitHub account):

   git clone git@github.com:yourusername/welcome-guide.git
   

   with https (requires login to GitHub account):

   git clone https://github.com/yourusername/welcome-guide.git
   

3. Create the default environment and install the project:

   with Hatch:

   hatch shell
   

   or with venv and pip:

   python3 -m venv .venv
   source .venv/bin/activate
   python3 -m pip install '.[test,dev,docs]'
   

4. Install the pre-commit hooks.

   pre-commit install-hooks