DOC: setup the documentation with Sphinx (#29)

.gitignore

@@ -4,4 +4,7 @@ __pycache__
 
 # Pytest
 .coverage
-.pytest_cache
+.pytest_cache
+
+# Sphinx
+_build

Makefile

@@ -0,0 +1,23 @@
+# 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     = docs
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+show:
+	python -m webbrowser -t "$(BUILDDIR)/html/index.html"
+
+.PHONY: help show 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)

README.md

@@ -10,7 +10,7 @@ M/EEG simulation framework
 
 3. Switch to the project folder and install the package and all dependencies: 
 
-```
+```bash
 cd meegsim
 pip install -e .[dev]
 ```
@@ -22,3 +22,24 @@ pip install -e .[dev]
 ```
 pytest
 ```
+
+## Building the Documentation
+
+1. Install the required packages.
+
+```bash
+pip install -e.[docs]
+```
+
+2. Build the documentation.
+
+```bash
+make html
+```
+
+3. Open it in the web browser.
+
+```bash
+make show
+```
+

docs/api/configuration.rst

@@ -0,0 +1,6 @@
+Source configuration
+====================
+
+.. automodule:: meegsim.configuration
+   :members:
+   :undoc-members:

docs/api/coupling.rst

@@ -0,0 +1,6 @@
+Coupling
+========
+
+.. automodule:: meegsim.coupling
+   :members:
+   :undoc-members:

docs/api/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   simulate
+   configuration
+   location
+   waveform
+   coupling

docs/api/location.rst

@@ -0,0 +1,6 @@
+Source location
+===============
+
+.. automodule:: meegsim.location
+   :members:
+   :undoc-members:

docs/api/simulate.rst

@@ -0,0 +1,6 @@
+Source simulator
+================
+
+.. automodule:: meegsim.simulate
+   :members:
+   :undoc-members:

docs/api/waveform.rst

@@ -0,0 +1,6 @@
+Source waveform
+===============
+
+.. automodule:: meegsim.waveform
+   :members:
+   :undoc-members:

docs/conf.py

@@ -0,0 +1,42 @@
+# 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
+
+import meegsim
+
+
+project = 'meegsim'
+copyright = '2024, MEEGsim Authors'
+author = 'MEEGsim Authors'
+release = meegsim.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon"
+]
+
+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 = 'pydata_sphinx_theme'
+html_static_path = ['_static']
+
+
+# Autodoc
+sys.path.insert(0, os.path.abspath('../src'))

docs/index.rst

@@ -0,0 +1,18 @@
+Welcome to meegsim's documentation!
+===================================
+
+
+.. toctree::
+   :maxdepth: 2
+
+   user_guide/index
+   api/index
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/user_guide/get_started.rst

@@ -0,0 +1,2 @@
+Getting Started
+===============

docs/user_guide/index.rst

@@ -0,0 +1,8 @@
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   install
+   get_started

docs/user_guide/install.rst

@@ -0,0 +1,8 @@
+Install
+=======
+
+Use the following command to install meegsim:
+
+.. code-block:: bash
+
+    pip install meegsim

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

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meegsim"
-version = "0.0.1"
+version = "0.0.1dev"
 authors = [
   { name="Nikolai Kapralov", email="[email protected]" },
   { name="Alina Studenova", email="[email protected]" },
@@ -33,6 +33,10 @@ dev = [
     "pytest",
     "pytest-cov"
 ]
+docs = [
+    "pydata-sphinx-theme",
+    "sphinx"
+]
 
 [tool.pytest.ini_options]
 pythonpath = "."

src/meegsim/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from importlib.metadata import version
+
+    __version__ = version("meegsim")
+except Exception:
+    __version__ = "0.0.0"

src/meegsim/coupling.py

@@ -1,20 +1,10 @@
 """
 Methods for setting the coupling between two signals
-All methods should accept the following arguments:
-  * time series of signal 1
-  * coupling parameters
-  * ideally, random_state (to allow reproducibility, still need to test how it would work)
-  
-All methods should return the time series of signals 1 and 2.
-
-Methods currently in mind:
-  * shifted copy (optionally with noise to control coupling parameters - later)
-  * phase phase coupling using von Mises distribution (within-frequency for now?)
 """
-import warnings
 
 import numpy as np
-import pytest
+import warnings
+
 from scipy.stats import vonmises
 from scipy.signal import butter, filtfilt, hilbert
 

src/meegsim/utils.py

@@ -128,13 +128,13 @@ def get_sfreq(times):
     """
     Calculate the sampling frequency of a sequence of time points.
 
-    Parameters:
+    Parameters
     ----------
     times: ndarray
         A sequence of time points assumed to be uniformly spaced.
 
-    Returns:
-    ----------
+    Returns
+    -------
     out : float
         The sampling frequency
     """

src/meegsim/waveform.py

@@ -1,21 +1,5 @@
 """
-All waveform functions should accept the following arguments:
-    * the shape of time series to generate (number of time series, time samples)
-    * all waveform-specific arguments should be keyword-only
-    * ideally, random_state (to allow reproducibility, still need to test how it would work)
-
-This can be achieved with the following template:
-
-def waveform_fn(n_series, times, *, kwarg1='aaa', kwarg2='bbb'):
-    pass
-    
-Waveforms currently in mind:
-    * narrowband_oscillation (a.k.a. filtered white noise)
-    * one_over_f_noise
-    * white_noise (for sensor space noise)
-
-Waveforms that are not urgent to have but could in principle be useful:
-    * non-sinusoidal stuff (harmonics, peak-trough asymmetry)
+Template waveforms: narrowband oscillation, white and 1/f noise
 """
 
 import colorednoise as cn