SecInterp - Development Guide

Welcome to the SecInterp development guide. This document outlines the standards, best practices, and workflows for contributing to the project.

---

🏗️ Technical Stack

• Language: Python 3.10+ (QGIS 3.x compatible)

• GUI Framework: PyQt5 (Native QGIS integration)

• Geospatial Engine: PyQGIS API (qgis.core, qgis.gui)

• Package Manager: uv (recommended) or pip

• Linter & Formatter: Ruff

• Testing: unittest (Standard Library)

---

🎨 Coding Standards

🧬 Design Principles

• SOLID: Follow SRP, OCP, and DIP strictly.

• Separation of Concerns: GUI code (Managers/UI) MUST NOT contain business logic. Delegating to Core/Services is mandatory.

• DRY (Don’t Repeat Yourself): If a calculation or check is used twice, move it to a core/utils module.

📝 Naming Conventions

• Classes: CapWords (e.g., ProfileService).

• Variables/Functions: snake_case (e.g., calculate_apparent_dip).

• Qt Overrides: camelCase (MUST match the original C++ signature, e.g., showEvent).

• Signals: camelCase (PyQt style, e.g., dataChanged).

🐍 Imports Ordering

1. Standard Library: os, sys, math, etc.

2. Third-Party: numpy, pandas, etc.

3. QGIS Core: from qgis.core import ...

4. QGIS GUI: from qgis.gui import ...

5. PyQt: from qgis.PyQt.QtWidgets import ... (Always use qgis.PyQt shim).

6. Local Modules: from sec_interp.core import ...

---

⚡ Git Workflow

Conventional Commits

All commits MUST follow the Conventional Commits specification:

Format: <type>(<scope>): <description>

• feat: A new feature (e.g., feat(drill): add 3d projection)

• fix: A bug fix (e.g., fix(gui): resolve range attribute error)

• refactor: Code change that neither fixes a bug nor adds a feature.

• docs: Documentation changes.

• test: Adding or correcting tests.

• chore: Build process or auxiliary tool changes.

Language: All commit messages must be in English.

---

🛠️ Tooling (Ruff)

We use Ruff for linting and formatting. It replaces Black, isort, and Flake8.

Basic Commands

# Lint and auto-fix
ruff check . --fix

# Format code
ruff format .

# Check everything (QA)
ruff check . && ruff format . --check

IDE Integration

It is highly recommended to install the Ruff extension in VS Code and enable “Format on Save”.

---

🧪 Testing

Running Tests (Local)

# Run all tests using the unified Makefile target
make test

Running Tests (Docker - Recommended)

To avoid dependency issues with QGIS, use the containerized environment:

# Build the image and run all tests in an isolated QGIS container
make docker-test

Mocking QGIS

When testing core services, use unittest.mock to avoid requiring a running QGIS instance. For integration tests in a headless environment, the project is configured to use QT_QPA_PLATFORM=offscreen.

---

📝 Documentation Standards

Docstrings

All public functions and methods MUST have docstrings in Google Style:

def process_data(self, layer: QgsVectorLayer, factor: float) -> Optional[list]:
    """
    Processes the layer using the specified scaling factor.

    Args:
        layer: The input QGIS vector layer.
        factor: The vertical exaggeration factor.

    Returns:
        A list of processed coordinates or None if invalid.
    """

Documentation Workflow

The project uses Sphinx to generate documentation. The build process is automated to publish results to a separate GitHub repository (sec_interp_docs) which serves as the source for GitHub Pages.

Building and Publishing

To build the documentation and automatically push changes to the docs repository:

./scripts/build_docs.sh

This script will:

1. Build HTML from docs/source.

2. Output to ../sec_interp_docs.

3. Check for changes in the output directory.

4. If changed, commit and push to geociencio/sec_interp_docs.

Note: You must have write access to the sec_interp_docs repository and have ../sec_interp_docs initialized as a git repo (which is done automatically if you follow setup).

Image Assets

Save all documentation images in docs/images/ using the following convention:

• workflow_DESC.png: Step-by-step guides.

• ui_DESC.png: General interface screenshots.

• feature_DESC.png: Specific highlighted features.

---

📦 Deployment & Makefile

Use the Makefile for common development tasks:

• make deploy: Installs the plugin into your local QGIS plugins folder.

• make zip: Creates a release-ready ZIP file.

• make test: Runs all unit and integration tests locally.

• make docker-build: Builds the testing Docker image.

• make docker-test: Builds and runs tests within a QGIS Docker container.

• make docus: Builds the Sphinx documentation.

• make clean: Removes temporary and compiled files.