sphinx documentation

.gitignore

@@ -164,4 +164,7 @@ cython_debug/
 # automatically created by setuptools_scm
 src/cedalion/_version.py
 
+# rendered example notebooks
+docs/examples/*.ipynb
+
 scratch/

docs/Makefile

@@ -0,0 +1,27 @@
+# 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 examples
+
+examples:
+	make -C examples notebooks
+
+clean_examples:
+	make -C examples clean
+
+
+# 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/conf.py

@@ -0,0 +1,41 @@
+# 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
+
+project = "cedalion"
+copyright = "2024, the cedalion developers"
+author = "the cedalion developers"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "nbsphinx",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+]
+
+myst_enable_extensions = [
+    "substitution",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+# -- Substitutions -----------------------------------------------------------
+
+myst_substitutions = {"docs_url": "https://eike.middell.net/share/cedalion/docs/"}

docs/environments.md

@@ -0,0 +1,3 @@
+# Environments
+
+TBD

docs/examples/Makefile

@@ -0,0 +1,19 @@
+EXAMPLE_NOTEBOOKS = new_conference_example1.ipynb \
+					new_conference_example2.ipynb \
+					pruning_and_motion_artifacts.ipynb \
+					photogrammetry.ipynb \
+					scalp_coupling_index.ipynb \
+					1010_system.ipynb
+
+
+
+.PHONY: notebooks
+
+notebooks: $(EXAMPLE_NOTEBOOKS)
+
+$(EXAMPLE_NOTEBOOKS) : %.ipynb : ../../examples/%.ipynb
+	jupyter nbconvert --ExecutePreprocessor.store_widget_state=True --to notebook \
+	      --execute --output-dir=. $^
+
+clean:
+	rm -f $(EXAMPLE_NOTEBOOKS)

docs/examples/index.md

@@ -0,0 +1,9 @@
+# Examples
+
+This section contains Jupyter notebooks that illustrate functionality of the toolbox.
+
+```{toctree}
+:maxdepth: 2
+:glob:
+*
+```

docs/getting_started/index.md

@@ -0,0 +1,6 @@
+# Getting started
+
+```{toctree}
+installation.md
+contributing_code/contributing_code.md
+```

docs/getting_started/installation.md

@@ -0,0 +1,40 @@
+# Installation
+
+## Development
+
+To create a conda environment with the necessary dependendencies run:
+
+```
+$ conda env create -n cedalion -f environment_dev.yml
+```
+
+Afterwards activate the environment and add an editable install of `cedalion` to it:
+```
+$ conda activate cedalion
+$ pip install -e .
+```
+
+This will also install Jupyter Notebook to run the example notebooks.
+
+
+```{admonition} If it's slow...
+:class: tip
+
+To create the environment conda needs to find a set of packages that fulfills all
+requirements. If conda needs too much time to find a solution, there are two ways to
+speed it up.
+
+1. Install [libmamba-solver](https://conda.github.io/conda-libmamba-solver/user-guide/)
+   and configure conda to use it. (***recommended***)
+
+2. Install [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), a drop-in replacement for conda.
+
+Additional guidance can be found in the the [environments section](environments.md).
+```
+
+
+
+## Production
+
+- TBD
+- currently, no fixed release. not on pypi.

docs/index.rst

@@ -0,0 +1,26 @@
+.. cedalion documentation master file, created by
+   sphinx-quickstart on Tue Feb 20 04:43:23 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Cedalion
+========
+
+A python-based framework for the data driven analysis of multimodal fNIRS and DOT in
+naturalistic environments.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   getting_started/index.md
+   examples/index.md
+   api.rst
+
+
+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

environment_dev.yml

@@ -39,6 +39,13 @@ dependencies:
   - pyvista
   - trame
   - vtk=9.2.2
+
+  - nbsphinx=0.9.3
+  - nbstripout=0.7.1
+  - sphinx
+  - myst-parser
+  - sphinx-autodoc-typehints
+
   - pip:
       - mne==1.4.0
       - mne-bids==0.12