This repository contains the source files for QGIS Tutorials and Tips at https://www.qgistutorials.com

The website is generated using Sphinx and source files are written using restructured text

To contribute or update the tutorials, you must install Sphinx locally, make changes to the .rst files, build the HTML pages and send a pull request.

The respository is very large and contains over 10 years of history. You don't need all the history locally, so just clone it with --depth 1 option to get only the latest files.

git clone --depth 1 [email protected]:spatialthoughts/qgis-tutorials.git --no-single-branch 
cd qgis-tutorials

The following instructions work for Linux/Mac systems. I prefer conda for environment management so the instructions use conda, but if you prefer virtualenv, you can use it instead as well.

Create a new environment named 'sphinx' and install dependencies. Most dependencies for sphinx based system are not yet available in conda, so we install pip and use it instead. Do not rely on your system pip as it will do a global install and may break your other python environments. We also need make to build the source files.

conda create --name sphinx
conda activate sphinx
conda install pip
conda install make
pip install -r requirements.txt

You also need to add the following line in your .bashrc or .zshrc to overcome a locate error

export LC_ALL=C

The preferred way to install sphinx and its dependencies on Windows is using Cygwin. Run the Cygwin installer and install the following packages from the installer

gcc-core
git
libjpeg-devel
make
python3-devel
python3.8-pip
zlib
zlib-devel

Once the packages are installed, open a Cygwin Terminal. Install the dependencies using the following commands. Pillow install via pip somehow fails. So use easy_install instead.

easy_install-3.8 pillow
pip3 install -r requirements.txt

From the root qgis-tutorials directory, run the following command

make html

This will generate HTML pages in build/html/ directory. Start a local HTTP server and preview them. Python comes with a built-in server that we can use

python -m http.server

A server will start on port 8000. Visit https://localhost:8000/build/html/en/ and preview the files.

Activate transifex-client with your API token. You need this only to pull new translations from transifex. The config file is stored in .tx/config.

tx config

Once configure, you can run the following command to pull new translations from Transifex

make transifex-pull

Once the changes are pushed to the main branch, run the following to update the gh_pages branch which serves the live website. You will need commit access to the repository to run this command.

make gh-pages

We prefer the following style while writing the tutorials.

All the tutorials are available under a Creative Commons Attribution 4.0 International License

Copyright 2021 Spatial Thoughts