ci:added pytest ci; modified readthedocs

.github/workflows/gtest.yaml

@@ -0,0 +1,26 @@
+name: GTest
+
+on:
+  push:
+    paths:
+      - '.github/workflows/gtest.yaml'
+      - 'skmap/src/**'
+      - 'skmap/include/**'
+      - 'tests/src/**'
+      - 'CMakeLists.txt'
+
+jobs:
+  gtest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgdal-dev build-essential
+      - name: run tests
+        run: |
+          cmake -B build -DTESTS=1 .
+          cmake --build build -j
+          ./build/tests/src/unit_tests
+

.github/workflows/pytest.yaml

@@ -0,0 +1,39 @@
+name: PyTest
+
+on:
+  push:
+    paths:
+     - '.github/workflows/pytest.yaml'
+     - 'skmap/**'
+     - 'tests/**'
+     - 'CMakeLists.txt'
+     - 'setup.py'
+     - 'pyproject.toml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libproj-dev libgeos-dev gdal-bin libgdal-dev
+          gdal-config --version
+      - name: Install the latest version of uv and set the python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: "true"
+      - name: install with python ${{ matrix.python-version }}
+        run: |
+          gdal-config --version
+          uv pip install .[full,dev]
+          . .venv/bin/activate
+      - name: Run format and tests
+        run: |
+          ruff format --check
+          pytest

.github/workflows/sphinx.yaml

@@ -0,0 +1,43 @@
+name: Python sphinx
+
+on:
+  push:
+    paths:
+      - '.github/workflows/sphinx.yaml'
+      - 'docs/**'
+      - 'skmap/**'
+      - 'CMakeLists.txt'
+      - 'setup.py'
+      - 'pyproject.toml'
+
+jobs:
+  doctest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libproj-dev libgeos-dev gdal-bin libgdal-dev pandoc doxygen build-essential
+          gdal-config --version
+      - name: Install the latest version of uv and set the python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          activate-environment: "true"
+      - name: Run doctests
+        run: |
+          gdal-config --version
+          uv pip install .[full,dev,docs]
+          doxygen
+          . .venv/bin/activate
+          sphinx-build -M doctest docs/ _build/
+      - name: Build docs
+        run: |
+          . .venv/bin/activate
+          sphinx-build docs/ _build/
+          rm -rf build/*.linux-*
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_build

.gitignore

@@ -1,13 +1,13 @@
 __pycache__
-build
+build/
+_build/
 dist
 *.egg*
 .vscode
 .ipynb_checkpoints
 skmap_data
 gapfilled
 tmp*
-docs/_build/
 docs/_autosummary/
 docs/notebooks/*.gpkg
 *.aux.xml
@@ -19,3 +19,7 @@ skmap_test.ipynb
 .cache/
 html/
 latex/
+xml/
+.*_cache/
+.venv/
+compile_commands.json

.readthedocs.yaml

@@ -7,6 +7,11 @@ sphinx:
 
 build:
    os: ubuntu-24.04
+   apt_packages:
+      - libproj-dev
+      - libgeos-dev
+      - gdal-bin
+      - libgdal-dev
    tools:
       python: "3.13"
    jobs:
@@ -17,5 +22,5 @@ build:
       create_environment:
          - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
       install:
-         - export UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv pip install . -r docs/requirements.txt 
-         - 
+         - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv pip install .[full] -r docs/requirements.txt
+

CMakeLists.txt

@@ -1,6 +1,8 @@
 cmake_minimum_required(VERSION 3.15...3.26)
 project(skmap_bindings LANGUAGES CXX)
 
+option(TESTS "Build unit tests" OFF)
+
 include(FetchContent)
 
 FetchContent_Declare(
@@ -28,13 +30,6 @@ find_package(OpenMP REQUIRED)
 message(STATUS "GDAL library: ${GDAL_LIBRARIES}")
 message(STATUS "GDAL headers: ${GDAL_INCLUDE_DIRS}")
 
-add_subdirectory("${pybind11_SOURCE_DIR}")
-
-include_directories("${eigen_SOURCE_DIR}")
-include_directories("${GDAL_INCLUDE_DIRS}")
-include_directories(skmap/include)
-include_directories(skmap/src)
-
 include(CheckCXXCompilerFlag)
 
 # List of AVX-512 flags to test
@@ -65,17 +60,53 @@ foreach(FLAG IN LISTS AVX512_CANDIDATES)
 endforeach()
 
 # Add all supported flags at once
-
-
 if(AVX512_FLAGS)
     # Always append -mfma when using AVX-512
     list(APPEND AVX512_FLAGS -mfma)
     add_compile_options(${AVX512_FLAGS})
     message(STATUS "Final AVX-512 compile options: ${AVX512_FLAGS}")
 endif()
 
+# -------------------------
+# LIBRARIES AND EXECS
+# -------------------------
+
+# create a core library for tests and bindings
+
+# all sources EXCEPT bindings
+set(
+    SOURCES
+    skmap/src/ParArray.cpp skmap/src/io/IoArray.cpp
+    skmap/src/transform/TransArray.cpp
+)
 
-set(SOURCES skmap/src/skmap_bindings.cpp skmap/src/ParArray.cpp skmap/src/io/IoArray.cpp skmap/src/transform/TransArray.cpp)
-pybind11_add_module(skmap_bindings ${SOURCES})
+add_library(skmap STATIC ${SOURCES})
+# we need to tell the static library that it will become part of a shared library in the bindings
+set_target_properties(skmap PROPERTIES POSITION_INDEPENDENT_CODE TRUE)
 
-target_link_libraries(skmap_bindings PRIVATE ${GDAL_LIBRARIES} OpenMP::OpenMP_CXX)
+target_include_directories(skmap PUBLIC
+    ${eigen_SOURCE_DIR}
+    ${GDAL_INCLUDE_DIRS}
+    skmap/include
+    skmap/src
+)
+target_link_libraries(skmap PUBLIC ${GDAL_LIBRARIES} OpenMP::OpenMP_CXX)
+if(AVX512_FLAGS)
+    target_compile_options(skmap PUBLIC ${AVX512_FLAGS})
+endif()
+
+# -------------------------
+# Python bindings
+# -------------------------
+
+set(BINDINGS_SOURCES skmap/src/skmap_bindings.cpp)
+pybind11_add_module(skmap_bindings ${BINDINGS_SOURCES})
+target_link_libraries(skmap_bindings PRIVATE skmap)
+
+# -------------------------
+# Tests
+# -------------------------
+if(TESTS)
+    enable_testing()
+    add_subdirectory(tests/src)
+endif()

CONTRIBUTING.md

@@ -14,11 +14,14 @@ For reporting issues and making feature suggestions please refer to the [issue t
 
 ### Initial setup
 
-1. Clone the repo: `git clone https://github.com/openlandmap/scikit-map.git`
+1. Clone the repo: `git clone git@github.com:openlandmap/scikit-map.git`
 2. Install dependencies (not needed if only contributing documentation):
-  - for the Python package: `pip install -r requirements.txt` into a Python 3.6+ environment
+   - Documentation: `uv pip install .[full,dev,docs] sphinx-autobuild`
+   - Code: `uv` doesn't like editable installs with our setup, after the above, re-run: `pip install -e .[full,dev,docs]` into a Python 3.6+ environment
 
-### Development
+This will ensure that a change to python files triggers a rebuild, as well as running `doxygen` again.
+
+### Development: Git
 
 All changes to code and documentation should be made in a separate branch, created from an up-to-date local `main`. The **branch name** must refer a open issue (``i{ISSUE_ID}``):
 
@@ -71,15 +74,62 @@ Must be one of the following:
 
 Based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
-### Code conventions
+### Documentation
+
+`scikit-map` is a mixed Python/C++ project. It auto-builds documentation from Python and C++ docstrings.
+
+1. For Python documentation live-updates run
+   ```bash
+   sphinx-autobuild docs/ _build/ --watch xml/
+   ```
+2. For C++: in the top-level directory, run `doxygen` to create xml documentation for `skmap_bindings`
+3. If you change C++ documentation, in a separate terminal run `doxygen` again and it will auto-update.
+
+### Python code
+
+
+#### Code conventions
 
 We strongly prefer to submit code to `scikit-map` with [type hints](https://docs.python.org/3/library/typing.html). Additionally, we support Python versions as low as 3.8 and no code that uses syntax introduced in later versions of Python (e.g. the walrus operator) will be accepted.
 
+Python code is formatted using ruff:
+
+```bash
+ruff format
+```
+
 There are currently no style restrictions guidelines imposed upon code contributions. This may change at a later date.
 
+### C++ code
+
+C++ code is formatted with clang-format:
+
+```bash
+# specify directories to omit build directory
+find {skmap/,tests/} -iname "*.cpp" -o -iname "*.h" | xargs clang-format --verbose -i
+```
+#### Clangd language server
+
+For code completion and intellisense. It needs a `compile_commands.json` at top-level. generate with:
+
+```bash
+cmake -B build -DTESTS=1 -DCMAKE_EXPORT_COMPILE_COMMANDS=1 .
+mv build/compile_commands.json .
+```
+#### Unit tests
+
+Unit tests with [`gtest`](https://google.github.io/googletest/quickstart-cmake.html) are included.
+
+To run:
+
+```bash
+cmake -B build -DTESTS=1 . # only have to run once
+cmake --build build -j && ./build/tests/src/unit_tests 
+```
+
 ### Versioning
 
-We adthere to standard [semantic versioning](https://semver.org/). Since we release from `main` <!-- needs to be discussed -->
+We adhere to standard [semantic versioning](https://semver.org/). Since we release from `main` <!-- needs to be discussed -->
 all merge requests should be accompanied with a version increment and the responsibility for increasing the version number falls on the contributor merging a branch: when merging a request either increment the MINOR version and reset the PATCH version to zero (if the intent of the merge request is to add new features) or increment the PATCH version (if the merge request only contains bugfixes). When merging a branch made by another contributor (e.g. because they do not have the required permissions to do so) please confirm the intent of the merge request (i.e. which semver number needs to be incremented).
 
-When incrementing the version of `scikit-map` it is enough to write the version change into [`__init__.py`](./skmap/__init__.py) in the appropriate branch.
+When incrementing the version of `scikit-map` it is enough to write the version change into [`pyproject.toml`](./pyproject.toml) in the appropriate branch.