IT-1338: Add docs for v2 API (#55)

Author: nosheen-adil

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme myst_parser isx
+      - name: Sphinx build
+        run: |
+          sphinx-build docs docs/build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/
+          force_orphan: true

CMakeLists.txt

@@ -1,5 +1,7 @@
 cmake_minimum_required(VERSION 3.5)
 
+project(isx)
+
 set(ISX_CMAKE_TOOLS_DIR ${CMAKE_CURRENT_LIST_DIR}/isxcore/tools/cmake)
 include(${ISX_CMAKE_TOOLS_DIR}/configure.cmake)
 include(${ISX_CMAKE_TOOLS_DIR}/core.cmake)

Makefile

@@ -1,5 +1,7 @@
-.PHONY: build test
+SHELL:=/bin/bash
+.PHONY: check_os build rebuild test docs
 
+# Build paths
 BUILD_DIR_ROOT=build
 BUILD_DIR_MODULES=modules
 BUILD_TYPE=Release
@@ -8,19 +10,26 @@ BUILD_DIR_BIN=bin
 BUILD_PATH=$(BUILD_DIR_ROOT)/$(BUILD_TYPE)/$(BUILD_DIR_CMAKE)
 BUILD_PATH_BIN=$(BUILD_DIR_ROOT)/$(BUILD_TYPE)/$(BUILD_DIR_BIN)
 
+# Test paths
 API_TEST_RESULTS_PATH=$(PWD)/apiTestResults.xml
 PYTHON_TEST_DIR=$(BUILD_DIR_ROOT)/$(BUILD_TYPE)/bin/isx
 
+# Check for test data dir
 ifndef TEST_DATA_DIR
 	TEST_DATA_DIR=test_data
 endif
 
+# Check for third party dir
 ifndef THIRD_PARTY_DIR
 	THIRD_PARTY_DIR=third_party
 endif
 
-PYTHON_VERSION=$(shell python -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+# Extract python version
+ifndef PYTHON_VERSION
+	PYTHON_VERSION=$(shell python -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+endif
 
+# Detect OS
 ifeq ($(OS), Windows_NT)
 	DETECTED_OS = windows
 else
@@ -30,6 +39,7 @@ else
 	else ifeq ($(UNAME_S), Darwin)
 		DETECTED_OS = mac
 
+# Set the macOS deployment version based on python version
 		ifeq ($(PYTHON_VERSION), 3.9)
 			_MACOSX_DEPLOYMENT_TARGET=10.11
 		else ifeq ($(PYTHON_VERSION), 3.10)
@@ -42,15 +52,17 @@ else
 	endif
 endif
 
+# Build flags for isxcore
 VERSION_MAJOR=2
 VERSION_MINOR=0
-VERSION_PATCH=0
+VERSION_PATCH=1
 VERSION_BUILD=0
 IS_BETA=1
 WITH_CUDA=0
 ASYNC_API=1
 WITH_ALGOS=0
 
+# Construct cmake options
 CMAKE_OPTIONS=\
     -DCMAKE_BUILD_TYPE=$(BUILD_TYPE)\
     -DISX_VERSION_MAJOR=${VERSION_MAJOR}\
@@ -62,6 +74,7 @@ CMAKE_OPTIONS=\
 	-DISX_ASYNC_API=${ASYNC_API} \
 	-DISX_WITH_ALGOS=${WITH_ALGOS} \
 
+# Define cmake generator based on OS
 ifeq ($(DETECTED_OS), windows)
 	CMAKE_GENERATOR = Visual Studio 14 2015 Win64
 else ifeq ($(DETECTED_OS), linux)
@@ -71,6 +84,22 @@ else ifeq ($(DETECTED_OS), mac)
 	CMAKE_GENERATOR = Xcode
 endif
 
+# Virtual environment vars
+ifndef VENV_NAME
+	VENV_NAME=pyisx
+endif
+
+# Define cmake generator based on OS
+ifeq ($(DETECTED_OS), windows)
+	VENV_ACTIVATE = source $(shell conda info --base)/Scripts/activate
+else
+	VENV_ACTIVATE = source $(shell conda info --base)/bin/activate
+endif
+
+ifndef BUILD_API
+	BUILD_API=0
+endif
+
 check_os:
 	@echo "Verifying detected OS"
 ifndef DETECTED_OS
@@ -84,6 +113,19 @@ endif
 
 clean:
 	@rm -rf build
+	@rm -rf docs/build
+
+ifeq ($(DETECTED_OS), mac)
+env:
+	CONDA_SUBDIR=osx-64 conda create -y -n $(VENV_NAME) python=$(PYTHON_VERSION) && \
+	$(VENV_ACTIVATE) $(VENV_NAME) && \
+	conda config --env --set subdir osx-64 && \
+	python -m pip install build
+else
+env:
+	conda create -y -n $(VENV_NAME) python=$(PYTHON_VERSION)
+	python -m pip install build
+endif
 
 ifeq ($(DETECTED_OS), mac)
 build: export MACOSX_DEPLOYMENT_TARGET=${_MACOSX_DEPLOYMENT_TARGET}
@@ -94,20 +136,31 @@ build: check_os
 	THIRD_PARTY_DIR=$(THIRD_PARTY_DIR) cmake $(CMAKE_OPTIONS) -G "$(CMAKE_GENERATOR)" ../../../
 ifeq ($(DETECTED_OS), windows)
 	cd $(BUILD_PATH) && \
-	"/c/Program Files (x86)/MSBuild/14.0/Bin/MSBuild.exe" Project.sln //p:Configuration=$(BUILD_TYPE) //maxcpucount:8
+	"/c/Program Files (x86)/MSBuild/14.0/Bin/MSBuild.exe" isx.sln //p:Configuration=$(BUILD_TYPE) //maxcpucount:8
 else ifeq ($(DETECTED_OS), linux)
 	cd $(BUILD_PATH) && \
 	make -j2
 else ifeq ($(DETECTED_OS), mac)
 	cd $(BUILD_PATH) && \
-	xcodebuild -alltargets -configuration $(BUILD_TYPE) -project Project.xcodeproj CODE_SIGN_IDENTITY=""
+	xcodebuild -alltargets -configuration $(BUILD_TYPE) -project isx.xcodeproj CODE_SIGN_IDENTITY=""
 endif
 	cd $(BUILD_PATH_BIN) && \
+	$(VENV_ACTIVATE) $(VENV_NAME) && \
 	python -m build
 
 rebuild: clean build
 
 test: build
-	cd $(BUILD_PATH_BIN)/dist && pip install --force-reinstall isx-*.whl
+	$(VENV_ACTIVATE) $(VENV_NAME) && \
+	pip install --force-reinstall '$(shell ls $(BUILD_PATH_BIN)/dist/isx-*.whl)[test]' && \
 	cd build/Release && \
 	ISX_TEST_DATA_PATH=$(TEST_DATA_DIR) python -m pytest --disable-warnings -v -s --junit-xml=$(API_TEST_RESULTS_PATH) test $(TEST_ARGS)
+
+ifeq ($(BUILD_API), 1)
+docs: build
+	$(VENV_ACTIVATE) $(VENV_NAME) && \
+	pip install --force-reinstall '$(shell ls $(BUILD_PATH_BIN)/dist/isx-*.whl)[docs]'
+endif
+docs:
+	$(VENV_ACTIVATE) $(VENV_NAME) && \
+	sphinx-build docs docs/build

README.md

@@ -1,10 +1,12 @@
 # pyisx
 
-`pyisx` is a python package for interacting with Inscopix data. This package encapsulates the following I/O functionality:
+The `pyisx` project is a python binding for [isxcore](https://github.com/inscopix/isxcore), a C++ API for interacting with Inscopix data.
+The python package for this binding, named `isx`, is available on [pypi](https://pypi.org/project/isx/) for download.
+This package encapsulates the following I/O functionality:
 
-* Reading Inscopix files (`.isxd`, `.isxc`, `.isxb`, `.gpio`, `.imu`)
+* Reading Inscopix files (`.isxd`, `.isxb`, `.gpio`, `.imu`)
 * Writing Inscopix files (`.isxd`)
-* Exporting Inscopix files to third-party formats (`.mp4`, `.tiff`, `.csv`, `.hdf5`)
+* Exporting Inscopix files to third-party formats (`.mp4`, `.tiff`, `.csv`)
 
 ## Install
 
@@ -14,30 +16,40 @@ Pre-built binaries of this API can be installed from [PyPi](https://pypi.org/pro
 pip install isx
 ```
 
+> **Note:** For Apple Silicon (i.e., macOS arm64 architecture), the package is currently not natively supported. However, it's possible to use anaconda to configure an x86 environment and use the project.
+
+```
+CONDA_SUBDIR=osx-64 conda create -n pyisx python=3.12
+conda activate pyisx
+conda config --env --set subdir osx-64
+pip install isx
+```
+
+
 ## Supported Platforms
 
-This library has been built and tested on the following operating systems:
+This library has been built and tested on the following operating systems, for python versions `3.9 - 3.12`.
 
 |  OS | Version | Architecture |
 |  --------- | ------- | ----- |
 | macOS   | 13 | x86_64 |
 | Ubuntu (Linux) | 20.04 | x86_64 |
 | Windows | 11 | amd64 |
 
-Each system has been built and tested on python versions 3.9 - 3.12.
-
-> **Note:** For Apple Silicon (arm64 architectures), the package is currently not natively supported. However, it's possible to use anaconda to configure an x86 environment and use the project.
-
-```
-CONDA_SUBDIR=osx-64 conda create -n pyisx python=3.12
-conda activate pyisx
-conda config --env --set subdir osx-64
-```
 
 ## Development Guide
 
 This guide documents how to build the python package wheel locally.
 
+1. Clone the repo
+
+Setup the repo and initialize its submodule:
+
+```bash
+git clone [email protected]:inscopix/pyisx.git
+git submodule update --init
+```
+
 1. Setup `isxcore`
 Follow the setup instructions for the C++ [isxcore](https://github.com/inscopix/isxcore) repo.
 
@@ -53,7 +65,7 @@ conda activate pyisx
 
 > **Note**: On macOS systems with Apple Silicon, the conda environment is configured differently, since `isxcore` is currently only built for x86 architectures.
 
-```
+```bash
 CONDA_SUBDIR=osx-64 conda create -n pyisx python=3.12
 conda activate pyisx
 conda config --env --set subdir osx-64
@@ -63,24 +75,24 @@ conda config --env --set subdir osx-64
 
 Inside the virtual environment install the following dependencies:
 
-```
+```bash
 conda install -y build pytest
 ```
 
 > **Note**: For python 3.12 the `build` package must be installed used `pip` instead.
 
 4. Build the package
 
-```
+```bash
 make build THIRD_PARTY_DIR=/path/to/third/party/dir
 ```
 
 5. Run the unit tests
 
-```
+```bash
 make test THIRD_PARTY_DIR=/path/to/third/party/dir TEST_DATA_DIR=/path/to/test/data/dir
 ```
 
 # Support
 
-For any questions about this package, please contact [email protected].com.
+For any questions or bug reports, please open an issue in our [issue tracker](https://github.com/inscopix/pyisx/issues).