From 6dcb2d5bb1c809972783b8c2796be9dec220f4f9 Mon Sep 17 00:00:00 2001 From: Nikolai Kapralov <4dvlup@gmail.com> Date: Fri, 6 Sep 2024 17:32:41 +0200 Subject: [PATCH 1/3] DOC: setup Sphinx --- .gitignore | 5 ++++- Makefile | 20 ++++++++++++++++++++ docs/conf.py | 28 ++++++++++++++++++++++++++++ docs/index.rst | 20 ++++++++++++++++++++ make.bat | 35 +++++++++++++++++++++++++++++++++++ pyproject.toml | 4 ++++ 6 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 make.bat diff --git a/.gitignore b/.gitignore index c30f27b..a3a55fe 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,7 @@ __pycache__ # Pytest .coverage -.pytest_cache \ No newline at end of file +.pytest_cache + +# Sphinx +_build \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..bbf99dd --- /dev/null +++ b/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 = docs +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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..d781841 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,28 @@ +# 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 = 'meegsim' +copyright = '2024, MEEGsim Authors' +author = 'MEEGsim Authors' +release = '0.0.1dev' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +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'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..fa348f4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. meegsim documentation master file, created by + sphinx-quickstart on Fri Sep 6 17:25:14 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to meegsim's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 3373509..8fd5d46 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,6 +33,10 @@ dev = [ "pytest", "pytest-cov" ] +docs = [ + "pydata-sphinx-theme", + "sphinx" +] [tool.pytest.ini_options] pythonpath = "." From 435609b8368def7be9169cdda520c1bd4f3965d3 Mon Sep 17 00:00:00 2001 From: Nikolai Kapralov <4dvlup@gmail.com> Date: Fri, 6 Sep 2024 18:46:52 +0200 Subject: [PATCH 2/3] DOC: populate the API reference --- docs/api/configuration.rst | 6 ++++++ docs/api/coupling.rst | 6 ++++++ docs/api/index.rst | 11 +++++++++++ docs/api/location.rst | 6 ++++++ docs/api/simulate.rst | 6 ++++++ docs/api/waveform.rst | 6 ++++++ docs/conf.py | 18 ++++++++++++++++-- docs/index.rst | 12 +++++------- docs/user_guide/get_started.rst | 2 ++ docs/user_guide/index.rst | 8 ++++++++ docs/user_guide/install.rst | 8 ++++++++ pyproject.toml | 2 +- src/meegsim/__init__.py | 6 ++++++ src/meegsim/coupling.py | 14 ++------------ src/meegsim/utils.py | 6 +++--- src/meegsim/waveform.py | 18 +----------------- 16 files changed, 93 insertions(+), 42 deletions(-) create mode 100644 docs/api/configuration.rst create mode 100644 docs/api/coupling.rst create mode 100644 docs/api/index.rst create mode 100644 docs/api/location.rst create mode 100644 docs/api/simulate.rst create mode 100644 docs/api/waveform.rst create mode 100644 docs/user_guide/get_started.rst create mode 100644 docs/user_guide/index.rst create mode 100644 docs/user_guide/install.rst diff --git a/docs/api/configuration.rst b/docs/api/configuration.rst new file mode 100644 index 0000000..5410e68 --- /dev/null +++ b/docs/api/configuration.rst @@ -0,0 +1,6 @@ +Source configuration +==================== + +.. automodule:: meegsim.configuration + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/api/coupling.rst b/docs/api/coupling.rst new file mode 100644 index 0000000..e782e33 --- /dev/null +++ b/docs/api/coupling.rst @@ -0,0 +1,6 @@ +Coupling +======== + +.. automodule:: meegsim.coupling + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..110ee47 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,11 @@ +API Reference +============= + +.. toctree:: + :maxdepth: 2 + + simulate + configuration + location + waveform + coupling \ No newline at end of file diff --git a/docs/api/location.rst b/docs/api/location.rst new file mode 100644 index 0000000..dd959b4 --- /dev/null +++ b/docs/api/location.rst @@ -0,0 +1,6 @@ +Source location +=============== + +.. automodule:: meegsim.location + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/api/simulate.rst b/docs/api/simulate.rst new file mode 100644 index 0000000..126f911 --- /dev/null +++ b/docs/api/simulate.rst @@ -0,0 +1,6 @@ +Source simulator +================ + +.. automodule:: meegsim.simulate + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/api/waveform.rst b/docs/api/waveform.rst new file mode 100644 index 0000000..0db0bd8 --- /dev/null +++ b/docs/api/waveform.rst @@ -0,0 +1,6 @@ +Source waveform +=============== + +.. automodule:: meegsim.waveform + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index d781841..695bf27 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,15 +6,25 @@ # -- 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 = '0.0.1dev' +release = meegsim.__version__ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon" +] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] @@ -26,3 +36,7 @@ html_theme = 'pydata_sphinx_theme' html_static_path = ['_static'] + + +# Autodoc +sys.path.insert(0, os.path.abspath('../src')) diff --git a/docs/index.rst b/docs/index.rst index fa348f4..8e04ce8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,12 @@ -.. meegsim documentation master file, created by - sphinx-quickstart on Fri Sep 6 17:25:14 2024. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to meegsim's documentation! =================================== + .. toctree:: :maxdepth: 2 - :caption: Contents: - + + user_guide/index + api/index Indices and tables @@ -18,3 +15,4 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + diff --git a/docs/user_guide/get_started.rst b/docs/user_guide/get_started.rst new file mode 100644 index 0000000..c3ce665 --- /dev/null +++ b/docs/user_guide/get_started.rst @@ -0,0 +1,2 @@ +Getting Started +=============== \ No newline at end of file diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst new file mode 100644 index 0000000..2fd63be --- /dev/null +++ b/docs/user_guide/index.rst @@ -0,0 +1,8 @@ +User Guide +========== + +.. toctree:: + :maxdepth: 2 + + install + get_started \ No newline at end of file diff --git a/docs/user_guide/install.rst b/docs/user_guide/install.rst new file mode 100644 index 0000000..9557f18 --- /dev/null +++ b/docs/user_guide/install.rst @@ -0,0 +1,8 @@ +Install +======= + +Use the following command to install meegsim: + +.. code-block:: bash + + pip install meegsim diff --git a/pyproject.toml b/pyproject.toml index 8fd5d46..7ad26c9 100644 --- a/pyproject.toml +++ b/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="kapralov@cbs.mpg.de" }, { name="Alina Studenova", email="studenova@cbs.mpg.de" }, diff --git a/src/meegsim/__init__.py b/src/meegsim/__init__.py index e69de29..41b7954 100644 --- a/src/meegsim/__init__.py +++ b/src/meegsim/__init__.py @@ -0,0 +1,6 @@ +try: + from importlib.metadata import version + + __version__ = version("meegsim") +except Exception: + __version__ = "0.0.0" \ No newline at end of file diff --git a/src/meegsim/coupling.py b/src/meegsim/coupling.py index 36bd133..513c7d5 100644 --- a/src/meegsim/coupling.py +++ b/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 diff --git a/src/meegsim/utils.py b/src/meegsim/utils.py index 1a8b634..d5237dd 100644 --- a/src/meegsim/utils.py +++ b/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 """ diff --git a/src/meegsim/waveform.py b/src/meegsim/waveform.py index b24d2b2..84733bf 100644 --- a/src/meegsim/waveform.py +++ b/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 From 6879b761e4f39eb35b9b3b570a13d9f4d7b36a88 Mon Sep 17 00:00:00 2001 From: Nikolai Kapralov <4dvlup@gmail.com> Date: Wed, 11 Sep 2024 13:17:35 +0200 Subject: [PATCH 3/3] DOC: added info about building docs to the README --- Makefile | 5 ++++- README.md | 23 ++++++++++++++++++++++- 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index bbf99dd..baaf39a 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,10 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +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). diff --git a/README.md b/README.md index ab41068..be8bc15 100644 --- a/README.md +++ b/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 +``` +