[DOC] Add sphinx documentation and serve on read the docs

.gitignore

@@ -1,8 +1,10 @@
-#
+# vscode files
 .vscode/
 
+# test related
+tests/outputs/
 
-# data folder
+# data folders
 data/
 
 # example output folders
@@ -13,6 +15,9 @@ figures/
 report.html
 ##*.png
 
+# pyenv
+Pipfile
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -54,6 +59,7 @@ pip-delete-this-directory.txt
 htmlcov/
 .tox/
 .coverage
+coverage_html
 .coverage.*
 .cache
 nosetests.xml
@@ -153,4 +159,3 @@ codegen/
 
 # Octave session info
 octave-workspace
-

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.1.0
+    hooks:
+      - id: check-yaml

.readthedocs.yml

@@ -0,0 +1,26 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  builder: html
+  fail_on_warning: false
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.6
+  install:
+    - requirements: requirements_dev.txt

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# CONTRIBUTING
+
+Information for anyone who would like to contribute to this repository.
+
+## Repository map
+
+```bash
+├── .git
+├── .github
+│   └── workflows         # Github continuous integration set up
+├── examples
+│   ├── data
+│   ├── example1outputs
+│   ├── example2outputs
+├── glmsingle             # Python implementation
+│   ├── cod
+│   ├── design
+│   ├── gmm
+│   ├── hrf
+│   ├── ols
+│   ├── ssq
+│   └── utils
+├── matlab                # Matlab implementation
+│   ├── examples
+│   ├── fracridge
+│   └── utilities
+└── tests                 # Python and Matlab tests
+    └── data
+
+```
+
+## Generic
+
+### Makefile
+
+### pre-commit
+
+## Matlab
+
+### Style guide
+
+### Tests
+
+#### Demos
+
+### Continuous integration
+
+## Python
+
+### Style guide
+
+### Tests
+
+#### Demos
+
+### Continuous integration

Makefile

@@ -0,0 +1,116 @@
+.DEFAULT_GOAL := help
+
+BROWSER := python -c "$$BROWSER_PYSCRIPT"
+
+# TODO make more general to use the local matlab version
+MATLAB = /usr/local/MATLAB/R2017a/bin/matlab
+MATLAB_ARG    = -nodisplay -nosplash -nodesktop
+
+define BROWSER_PYSCRIPT
+import os, webbrowser, sys
+
+from urllib.request import pathname2url
+
+webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
+endef
+export BROWSER_PYSCRIPT
+
+# determines what "make help" will show
+define PRINT_HELP_PYSCRIPT
+import re, sys
+
+for line in sys.stdin:
+	match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
+	if match:
+		target, help = match.groups()
+		print("%-20s %s" % (target, help))
+endef
+export PRINT_HELP_PYSCRIPT
+
+################################################################################
+# 	GENERIC
+.PHONY: help clean clean-test lint install_dev
+
+help:
+	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
+clean: clean-build clean-pyc clean-test ## remove all build, test, coverage artifacts
+
+clean-test: ## remove test and coverage artifacts
+	rm -rf .tox/
+	rm -rf .coverage
+	rm -rf htmlcov/
+	rm -rf .pytest_cache
+	rm -rf tests/data
+	rm -rf test/outputs
+
+install_dev: ## install for both matlab and python developpers
+	pip install -e .
+	pip install -r requirements_dev.txt
+
+lint: lint/black lint/flake8 lint/miss_hit ## check style
+
+test: test-matlab test-python
+
+tests/data/nsdcoreexampledataset.mat: 
+	mkdir tests/data
+	curl -fsSL --retry 5 -o "tests/data/nsdcoreexampledataset.mat" https://osf.io/k89b2/download
+
+################################################################################
+
+################################################################################
+# 	MATLAB
+
+.PHONY: lint/miss_hit
+
+lint/miss_hit: ## lint and checks matlab code
+	mh_style --fix tests && mh_metric --ci tests && mh_lint tests
+
+test-matlab: tests/data/nsdcoreexampledataset.mat
+	$(MATLAB) $(MATLAB_ARG) -r "run_tests; exit()"
+
+coverage-matlab: test-matlab
+	$(BROWSER) coverage_html/index.html
+
+################################################################################
+
+################################################################################
+# 	PYTHON
+
+.PHONY: clean-build clean-pyc coverage-python install lint/flake8 lint/black
+
+clean-build: ## remove build artifacts
+	rm -fr build/
+	rm -fr dist/
+	rm -fr .eggs/
+	find . -name '*.egg-info' -exec rm -fr {} +
+	find . -name '*.egg' -exec rm -f {} +
+
+clean-pyc: ## remove Python file artifacts
+	find . -name '*.pyc' -exec rm -f {} +
+	find . -name '*.pyo' -exec rm -f {} +
+	find . -name '*~' -exec rm -f {} +
+	find . -name '__pycache__' -exec rm -fr {} +
+
+lint/flake8: ## check style with flake8
+	flake8 tests
+lint/black: ## check style with black
+	black tests
+
+test-python: tests/data/nsdcoreexampledataset.mat ## run tests quickly with the default Python
+	pytest 
+
+test-notebooks:
+	pytest  --nbmake --nbmake-timeout=3000 "./examples"
+test-all: ## run tests on every Python version with tox
+	tox
+
+coverage-python: ## check code coverage quickly with the default Python
+	coverage run --source glmsingle -m pytest
+	coverage report -m
+	coverage html
+	$(BROWSER) htmlcov/index.html
+
+install: clean ## install the package to the active Python's site-packages
+	python setup.py install
+
+################################################################################

README.md

@@ -33,20 +33,6 @@ This will also clone [`fracridge`](https://github.com/nrdg/fracridge) as a submo
 
 To use the GLMsingle toolbox, add it and `fracridge` to your MATLAB path by running the `setup.m` script.
 
-## Example scripts
-
-We provide a number of example scripts that demonstrate usage of GLMsingle. You can browse these example scripts here:
-
-(Python Example 1 - event-related design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/examples/example1.html
-
-(Python Example 2 - block design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/examples/example2.html
-
-(MATLAB Example 1 - event-related design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/matlab/examples/example1preview/example1.html
-
-(MATLAB Example 2 - block design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/matlab/examples/example2preview/example2.html
-
-If you would like to run these example scripts, the Python versions are available in `/GLMsingle/examples`, and the MATLAB versions are available in `/GLMsingle/matlab/examples`. Each notebook contains a full walkthrough of the process of loading an example dataset and design matrix, estimating neural responses using GLMsingle, estimating the reliability of responses at each voxel, and comparing those achieved via GLMsingle to those achieved using a baseline GLM.
-
 ## Python
 
 To install: 
@@ -63,12 +49,25 @@ Running the demos requires:
 pip install jupyterlab
 ```
 
-Code dependencies: see requirements.txt
+Code dependencies: see [requirements.txt](./requirements.txt)
 
 Notes:
-* Please note that GLMsingle is not (yet) compatible with Python 3.9 (due to an incompatibility between scikit-learn and Python 3.9). Please use Python 3.8 or earlier.
 * Currently, numpy has a 4GB limit for the pickle files it writes; thus, GLMsingle will crash if the file outputs exceed that size. One workaround is to turn off "disk saving" and instead get the outputs of GLMsingle in your workspace and save the outputs yourself to HDF5 format.
 
+## Example scripts
+
+We provide a number of example scripts that demonstrate usage of GLMsingle. You can browse these example scripts here:
+
+(Python Example 1 - event-related design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/examples/example1.html
+
+(Python Example 2 - block design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/examples/example2.html
+
+(MATLAB Example 1 - event-related design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/matlab/examples/example1preview/example1.html
+
+(MATLAB Example 2 - block design) https://htmlpreview.github.io/?https://github.com/kendrickkay/GLMsingle/blob/main/matlab/examples/example2preview/example2.html
+
+If you would like to run these example scripts, the Python versions are available in `/GLMsingle/examples`, and the MATLAB versions are available in `/GLMsingle/matlab/examples`. Each notebook contains a full walkthrough of the process of loading an example dataset and design matrix, estimating neural responses using GLMsingle, estimating the reliability of responses at each voxel, and comparing those achieved via GLMsingle to those achieved using a baseline GLM.
+
 ## Additional information
 
 For additional information, please visit the Wiki page associated with this
@@ -80,6 +79,10 @@ If you use GLMsingle in your research, please cite the following paper:
 
 * [Prince, J.S., Charest, I., Kurzawski, J.W., Pyles, J.A., Tarr, M.J., Kay, K.N. GLMsingle: a toolbox for improving single-trial fMRI response estimates. bioRxiv (2022).](https://www.biorxiv.org/content/10.1101/2022.01.31.478431v1)
 
+## Contributing
+
+If you want to contribute to GLMsingle see the [contributing](./CONTRIBUTING.md) documentation to help you know what is where and how to set things up.
+
 ## Change history
 
 * 2021/10/12 - Version 1.0 of GLMsingle is now released. A git tag has been added to the repo.

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     = source
+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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+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