Skip to content

Developer Guide

Welcome to the Species Explorer Developer Guide! This section covers development setup, architecture, and contribution guidelines.

Getting Started

Quick Start for Developers

1. Clone the Repository

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

2. Enter Development Environment

Using Nix (recommended): 

nix develop

This provides all development tools including:

  • Python with QGIS bindings
  • Testing tools (pytest, coverage)
  • Code quality tools (black, flake8, isort)
  • Documentation tools (mkdocs)
nix run .#symlink

4. Launch QGIS

nix run .#qgis

Development Workflow

graph LR
    A[Code] --> B[Format]
    B --> C[Lint]
    C --> D[Test]
    D --> E[Commit]
    E --> F[PR]

Common Commands

Command Description
nix run .#format Format code with black and isort
nix run .#lint Run linters (flake8, pylint)
nix run .#test Run test suite with coverage
nix run .#docs-serve Serve documentation locally
nix run .#checks Run pre-commit checks

Code Standards

  • Python 3.9+ target version
  • 120 character line length
  • Black for code formatting
  • Google-style docstrings
  • Type hints encouraged

Testing

Run the test suite:

nix run .#test

View coverage report:

open htmlcov/index.html

Documentation

Build and serve docs locally:

nix run .#docs-serve

Open http://localhost:8000 in your browser.

Need Help?

Made with 💗 by Kartoza | Donate | GitHub