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.