Added SensingClues-tutorial and underlying functionality

.github/workflows/python-package.yml

@@ -0,0 +1,42 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Test Python package
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        if [ -f requirements_dev.txt ]; then pip install -r requirements_dev.txt; fi
+        python -m pip install .
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest

.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -76,6 +76,7 @@ docs/_build/
 target/
 
 # Jupyter Notebook
+*.ipynb
 .ipynb_checkpoints
 
 # IPython
@@ -157,4 +158,4 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/

.readthedocs.yaml

@@ -0,0 +1,28 @@
+# Read the Docs configuration file for Sphinx projects
+
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements_docs.txt
+    - method: pip
+      path: .
+
+

README.md

@@ -1,2 +1,66 @@
-# sensingcluespy
-Python client for  Cluey app
+# Python API to extract SensingClues data 
+
+## Introduction
+
+[SensingClues](https://sensingclues.org/) allows you to record, monitor and analyze wildlife observations to support nature conservation initiatives.
+The package ``sensingcluespy`` allows Python-users to connect to SensingClues' database and download
+data logged using the Cluey-app. This includes wildlife observations and tracks, custom map layers,
+and the wildlife ontology used by SensingClues. **Note:** you need credentials for the 
+SensingClues [Cluey](https://sensingclues.org/cluey)-app to connect to the database.
+
+See the installation and usage instructions below. For more details, see 
+[API-documentation](https://sensingcluespy.readthedocs.io/en/latest/#).
+
+## Installation
+
+There are various methods to install `sensingcluespy`. For any method, we recommend using a virtual environment when installing the library, such as pyenv or virtualenv.
+
+The simplest method is to install ``sensingcluespy`` directly from pypi::
+```python
+pip install sensingcluespy
+```
+
+To download the source code and install the library:
+```python
+git clone https://github.com/SensingClues/sensingcluespy.git
+cd </parent_location_of_the_library/sensingcluespy/>
+pip install .
+pip install -r requirements.txt
+```
+
+Further, we recommend using `jupytext` when working with Jupyter notebooks. Install it like so:
+```python
+pip install jupytext
+```
+
+Finally, you should create a personal account for SensingClues using the Cluey Data Collector app, which can be 
+downloaded from the Google Playstore (not supported for iOS currently). 
+Also see [here](https://sensingclues.org/portal).
+
+Note: if you are developing new functionality, please also do:
+```python
+pip install -r requirements_dev.txt
+pre-commit install
+```
+
+## Usage
+
+The best way to get acquainted with the functionality availability in `sensingcluespy` is 
+to check the notebook `notebooks/sensingclues_tutorial.py.`
+
+Methods which are currently implemented are:
+- `login` and `logout`: Connect to the database.
+- `get_groups`: Obtain overview of groups you have access to.
+- `get_observations`: Extract observations. 
+- `get_tracks`: Extract track data.
+- `add_geojson_to_tracks`: Add geospatial information to track data.
+- `get_all_layers`: Obtain overview of all layers you have access to.
+- `get_layer_features`: Extract detailed information on a layer.
+- `get_hierarchy`: Get full hierarchy (ontology) used in database.
+- helper functions related to the hierarchy/ontology, such as `get_label_for_id` and
+`get_children_for_label`
+- `get_concept_counts`: Get number of occurrences for a specific concept in the ontology.
+
+The data can be filtered on for instance dates, coordinates and specific elements in the ontology.
+See the detailed [API-documentation](https://sensingcluespy.readthedocs.io/en/latest/#) 
+of each function to check which filters are available. 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,4 @@
+
+.wy-nav-content {
+    max-width: 70%;
+}

docs/conf.py

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
+
+project = "sensingcluespy"
+copyright = "2024, SensingClues"
+author = "SensingClues"
+release = "0.2.2"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+def setup(app):  # custom css is used to change the css used
+    app.add_css_file('css/custom.css')
+
+
+extensions = [
+    'nbsphinx',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+]
+
+# prevent execution of demo notebooks upon building on readthedocs
+nbsphinx_execute = 'never'
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+sphinxsql_include_table_attributes = True
+autodoc_typehints = "description" #add the types to the parameter in autodoc
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+source_suffix = [".rst", ".md"]
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+

docs/index.rst

@@ -0,0 +1,31 @@
+.. sensingcluespy documentation master file, created by
+   sphinx-quickstart on Thu Oct  6 21:46:31 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to SensingClues documentation!
+======================================
+
+.. include:: source/introduction.rst
+
+.. toctree::
+   :maxdepth: 2
+
+   source/installation.rst
+   source/usage.rst
+   source/tutorial.rst
+
+Source code documentation
+-------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   source/code
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd