This repository contains the source files for QGIS Tutorials and Tips at http://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 repository is very large and contains over 10 years of history (See maintenance). 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 git@github.com:spatialthoughts/qgis-tutorials.git
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 http://localhost:8000/build/html/en/ and preview the files.
-
Install the latest
transifex-client. Update thePATHvariable to include path to thetxcommand. -
Get a new API token from https://app.transifex.com/user/settings/api/.
-
Create a
.transifexrcfile in your home directory with the following content and replaceyour API tokenwith your actual token.
[https://www.transifex.com]
rest_hostname = https://rest.api.transifex.com
token = <your API token>
- Once configure, you can run the following command to pull new translations from Transifex
make transifex-pull
Commit and push the changes to the main branch.
There is a GitHub action active on the repository that automatically builds and pushes changes to gh-pages on every commit to the main branch.
If you need to manually push the changes to GitHub pages, run the following command
git fetch
make gh-pages
We prefer the following style while writing the tutorials.
| Type | rst Formatting |
|---|---|
| Title | ========== |
| Heading 1 | ---------- |
| Heading 2 | ^^^^^^^^^^ |
| Heading 3 | """""""""" |
| Menu items | :menuselection:`menu --> submenu1 --> submenu2` |
| Processing algorithms | :menuselection:`Processing Toolbox --> Vector Overlay --> Clip` |
| Window titles, Tabs, Dialogs and buttons | :guilabel:`label` |
| Error and info messages | *information* |
| Keyboard shortcuts | kbd:`Ctrl+L` |
| Layer and file names | ``layer_name`` |
| Text input by the user | ``value`` |
| External web links | `name <url>`_ |
This repository becomes quite large over time — particularly the gh-pages branch. We don't need to keep the full history of the built pages, so we periodically prune it using the orphan branch method below.
git checkout gh-pages
git checkout --orphan last
git add -A
git commit -am 'fresh init'
git branch -D gh-pages
git branch -m gh-pages
git push -f origin gh-pages
git gc --aggressive --prune=all
All the tutorials are available under a Creative Commons Attribution 4.0 International License
Copyright 2026 Spatial Thoughts