Skip to content

Development Setup

This guide covers setting up your development environment for Species Explorer.

Prerequisites

  • Git for version control
  • QGIS 3.0+ or Nix for QGIS provision
  • Python 3.9+
  • Nix (recommended) for reproducible environment

1. Install Nix

If you don't have Nix installed:

curl -L https://nixos.org/nix/install | sh

Enable flakes in your Nix configuration:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

2. Clone the Repository

git clone https://github.com/kartoza/SpeciesExplorer.git
cd SpeciesExplorer

3. Enter Development Shell

nix develop

This provides:

  • Python environment with all dependencies
  • QGIS
  • Code quality tools (black, flake8, isort, pylint)
  • Testing tools (pytest, coverage)
  • Documentation tools (mkdocs)
  • Pre-commit hooks

4. Allow direnv (Optional)

If you use direnv:

direnv allow

The environment will activate automatically when entering the directory.

Setup without Nix

1. Clone the Repository

git clone https://github.com/kartoza/SpeciesExplorer.git
cd SpeciesExplorer

2. Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate  # Windows

3. Install Dependencies

pip install -r REQUIREMENTS.txt
pip install -r REQUIREMENTS_TESTING.txt

4. Install QGIS

Install QGIS 3.x from your system package manager or qgis.org.

To test the plugin in QGIS, create a symlink:

ln -s $(pwd)/species_explorer ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/SpeciesExplorer

ln -s $(pwd)/species_explorer ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins/SpeciesExplorer

mklink /D "%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\SpeciesExplorer" "species_explorer"

Or use the Nix command:

nix run .#symlink

IDE Setup

Neovim

The repository includes .exrc and .nvim.lua for Neovim integration:

  • WhichKey shortcuts under <leader>p
  • LSP configuration with Pyright
  • DAP debugging support

VS Code

Recommended extensions:

  • Python
  • Pylance
  • QGIS Plugin Development

Create .vscode/settings.json:

{
  "python.analysis.extraPaths": [
    "/usr/share/qgis/python",
    "/usr/share/qgis/python/plugins"
  ],
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true
}

PyCharm

  1. Set Python interpreter to your QGIS Python
  2. Add QGIS Python paths to project structure
  3. Enable Black formatter

Pre-commit Hooks

Install pre-commit hooks:

pre-commit install

Run checks manually:

pre-commit run --all-files

Or using Nix:

nix run .#checks

Compile Resources

If you modify resources.qrc:

pyrcc5 -o species_explorer/resources.py species_explorer/resources.qrc

Running Tests

# With Nix
nix run .#test

# Without Nix
pytest test/ -v --cov=species_explorer

Building Documentation

# Serve locally
nix run .#docs-serve

# Build static site
nix run .#docs-build

Troubleshooting

QGIS Python Not Found

Add QGIS to your Python path:

export PYTHONPATH="/usr/share/qgis/python:$PYTHONPATH"

Pre-commit Fails

  • Ensure all tools are installed
  • Run pre-commit clean and try again
  • Check specific hook errors

Tests Fail

  • Ensure QGIS is properly configured
  • Check that all dependencies are installed
  • Run with -v for verbose output

Made with 💗 by Kartoza | Donate | GitHub