Download and build

You want to improve this guide? Let’s start by building the documentation locally on your machine!

We will use, GitHub, git, Python, Python’s venv module, and Sphinx.

Note

Some of the steps below assumes some level of familiarity with the tools. If you don’t know where to start exactly, do not panic! Contact me and we can go through this together and find out what to add to make this guide even better.

Fork and clone the repository

When contributing to a project hosted on GitHub is a good practice to fork the project first under your username and clone your fork locally.

git clone https://github.com/<YOUR-USER-NAME>/i18n-handbook.git
cd i18n-handbook

It’s also a good practice to keep an eye what happens upstream (source repository) by configuring a remote on your clone.

git remote add upstream https://github.com/carpentries-i18n/i18n-handbook.git

Creating an environment

To build the documentation locally it’s recommended that you create an environment with the dependencies. For example on Linux or OSX you can do as:

python -m venv ~/.venv/i18n-sphinx
source ~/.venv/i18n-sphinx/bin/activate
pip install -r requirements.txt

refer to the venv tutorial to see how this is done on Windows.

Build the documentation

Once you’ve got your environment setup you can go ahead and build the documentation locally with:

sphinx-build -b html . _build

To see what you’ve built then use:

python -m http.server --directory _build/html

That will serve the page on your machine under http://localhost:8000 and you can see from your browser.