From e3b5d2d6cc6282b6af2aa0ba6bc5d137bedc57f1 Mon Sep 17 00:00:00 2001
From: Jan Grewe <jan.grewe@g-node.org>
Date: Sat, 1 Jun 2024 20:21:14 +0200
Subject: [PATCH] documentation
---
build_docs.sh | 74 +++++++++++++++++++++++++++++++++++++
docs/etrack.md | 35 ++++++++++++++++++
docs/trackingdata.md | 4 ++
mkdocs.yml | 17 +++++++++
pyproject.toml | 2 +-
src/etrack/__init__.py | 7 ++++
src/etrack/arena.py | 3 ++
src/etrack/image_marker.py | 9 +++--
src/etrack/info.py | 3 ++
src/etrack/io/__init__.py | 3 ++
src/etrack/tracking_data.py | 4 ++
src/etrack/util.py | 3 ++
12 files changed, 160 insertions(+), 4 deletions(-)
create mode 100755 build_docs.sh
create mode 100644 docs/etrack.md
create mode 100644 docs/trackingdata.md
create mode 100644 mkdocs.yml
diff --git a/build_docs.sh b/build_docs.sh
new file mode 100755
index 0000000..6205316
--- /dev/null
+++ b/build_docs.sh
@@ -0,0 +1,74 @@
+#!/bin/bash
+
+die() { echo "ERROR: $*"; exit 2; }
+warn() { echo "WARNING: $*"; }
+
+for cmd in mkdocs pdoc3 genbadge; do
+ command -v "$cmd" >/dev/null ||
+ warn "missing $cmd: run \`pip install $cmd\`"
+done
+
+PACKAGE="etrack"
+PACKAGESRC="src/$PACKAGE"
+PACKAGEROOT="$(dirname "$(realpath "$0")")"
+BUILDROOT="$PACKAGEROOT/site"
+
+# check for code coverage report:
+# need to call nosetest with --with-coverage --cover-html --cover-xml
+HAS_COVER=false
+test -d cover && HAS_COVER=true
+
+echo
+echo "Clean up documentation of $PACKAGE"
+echo
+
+rm -rf "$BUILDROOT" 2> /dev/null || true
+mkdir -p "$BUILDROOT"
+
+if command -v mkdocs >/dev/null; then
+ echo
+ echo "Building general documentation for $PACKAGE"
+ echo
+
+ cd "$PACKAGEROOT"
+ cp .mkdocs.yml mkdocs-tmp.yml
+ if $HAS_COVER; then
+ echo " - Coverage: 'cover/index.html'" >> mkdocs-tmp.yml
+ fi
+ mkdir -p docs
+ sed -e 's|docs/||; /\[Documentation\]/d; /\[API Reference\]/d' README.md > docs/index.md
+ mkdocs build --config-file mkdocs.yml --site-dir "$BUILDROOT"
+ rm mkdocs-tmp.yml docs/index.md
+ cd - > /dev/null
+fi
+
+if $HAS_COVER; then
+ echo
+ echo "Copy code coverage report and generate badge for $PACKAGE"
+ echo
+
+ cd "$PACKAGEROOT"
+ cp -r cover "$BUILDROOT/"
+ genbadge coverage -i coverage.xml
+ # https://smarie.github.io/python-genbadge/
+ mv coverage-badge.svg site/coverage.svg
+ cd - > /dev/null
+fi
+
+if command -v pdoc3 >/dev/null; then
+ echo
+ echo "Building API reference docs for $PACKAGE"
+ echo
+
+ cd "$PACKAGEROOT"
+ pdoc3 --html --config latex_math=True --config sort_identifiers=False --output-dir "$BUILDROOT/api-tmp" $PACKAGESRC
+ mv "$BUILDROOT/api-tmp/$PACKAGE" "$BUILDROOT/api"
+ rmdir "$BUILDROOT/api-tmp"
+ cd - > /dev/null
+fi
+
+echo
+echo "Done. Docs in:"
+echo
+echo " file://$BUILDROOT/index.html"
+echo
\ No newline at end of file
diff --git a/docs/etrack.md b/docs/etrack.md
new file mode 100644
index 0000000..8e4dcec
--- /dev/null
+++ b/docs/etrack.md
@@ -0,0 +1,35 @@
+# E-Fish tracking
+
+Tool for easier handling of tracking results.
+
+## Installation
+
+### 1. Clone git repository
+
+```shell
+git clone https://whale.am28.uni-tuebingen.de/git/jgrewe/efish_tracking.git
+```
+
+### 2. Change into directory
+
+```shell
+cd efish_tracking
+````
+
+### 3. Install with pip
+
+```shell
+pip3 install -e . --user
+```
+
+The ```-e``` installs the package in an *editable* model that you do not need to reinstall whenever you pull upstream changes.
+
+If you leave away the ```--user``` the package will be installed system-wide.
+
+## TrackingResults
+
+Is a class that wraps around the *.h5 files written by DeepLabCut
+
+## ImageMarker
+
+Class that allows for creating MarkerTasks to get specific positions in a video.
\ No newline at end of file
diff --git a/docs/trackingdata.md b/docs/trackingdata.md
new file mode 100644
index 0000000..9f1972b
--- /dev/null
+++ b/docs/trackingdata.md
@@ -0,0 +1,4 @@
+# TrackingData
+
+Class that represents the position data associated with one noe/bodypart.
+
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..772cd31
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,17 @@
+site_name: etrack
+
+repo_url: https://github.com/bendalab/etrack/
+
+edit_uri: ""
+
+site_author: Jan Grewe jan.grewe@g-node.org
+
+theme: readthedocs
+
+nav:
+ - Home: 'index.md'
+ - 'User guide':
+ - 'etrack': 'etrack.md'
+ - 'TrackingData' : 'trackingdata.md'
+ - 'Code':
+ - API reference: 'api/index.html'
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index a54656d..8d9dbe2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
name = "etrack"
dynamic = ["version"]
dependencies = [
- "nixio>=1.5",
+ "hdf5",
"nixtrack",
"numpy",
"matplotlib",
diff --git a/src/etrack/__init__.py b/src/etrack/__init__.py
index dcaf5a6..2738546 100644
--- a/src/etrack/__init__.py
+++ b/src/etrack/__init__.py
@@ -1,3 +1,10 @@
+# -*- coding: utf-8 -*-
+""" etrack package for easier reading and handling of efish tracking data.
+
+Copyright © 2024, Jan Grewe
+
+Redistribution and use in source and binary forms, with or without modification, are permitted under the terms of the BSD License. See LICENSE file in the root of the Project.
+"""
from .image_marker import ImageMarker, MarkerTask
from .tracking_result import TrackingResult, coordinate_transformation
from .arena import Arena, Region
diff --git a/src/etrack/arena.py b/src/etrack/arena.py
index 73cb48a..c1e14ab 100644
--- a/src/etrack/arena.py
+++ b/src/etrack/arena.py
@@ -1,3 +1,6 @@
+"""
+Classes to construct the arena in which the animals were tracked.
+"""
import logging
import numpy as np
import matplotlib.pyplot as plt
diff --git a/src/etrack/image_marker.py b/src/etrack/image_marker.py
index 136bb78..c853dc9 100644
--- a/src/etrack/image_marker.py
+++ b/src/etrack/image_marker.py
@@ -1,8 +1,11 @@
-import matplotlib.pyplot as plt
-import cv2
+"""
+Module that defines the ImageMarker and MarkerTask classes to manually mark things in individual images.
+"""
import os
+import cv2
import sys
-from IPython import embed
+import matplotlib.pyplot as plt
+
class ImageMarker:
diff --git a/src/etrack/info.py b/src/etrack/info.py
index 14d4179..41abd5e 100644
--- a/src/etrack/info.py
+++ b/src/etrack/info.py
@@ -6,6 +6,9 @@
# Redistribution and use in source and binary forms, with or without
# modification, are permitted under the terms of the BSD License. See
# LICENSE file in the root of the Project.
+"""
+Package info.
+"""
import os
import json
diff --git a/src/etrack/io/__init__.py b/src/etrack/io/__init__.py
index e69de29..0e0475b 100644
--- a/src/etrack/io/__init__.py
+++ b/src/etrack/io/__init__.py
@@ -0,0 +1,3 @@
+"""
+Reader classes for DeepLabCut, or SLEAP written data files.
+"""
diff --git a/src/etrack/tracking_data.py b/src/etrack/tracking_data.py
index 6d8b958..8703ba6 100644
--- a/src/etrack/tracking_data.py
+++ b/src/etrack/tracking_data.py
@@ -1,3 +1,7 @@
+"""
+Module that defines the TrackingData class that wraps the position data for a given node/bodypart that has been tracked.
+"""
+
import numpy as np
diff --git a/src/etrack/util.py b/src/etrack/util.py
index 7b9ca9a..af7ced0 100644
--- a/src/etrack/util.py
+++ b/src/etrack/util.py
@@ -1,3 +1,6 @@
+"""
+Module containing utility functions and enum classes.
+"""
from enum import Enum
class Illumination(Enum):