Merge branch 'main' into nat_behav

.github/workflows/docs_build_and_deploy.yml

@@ -0,0 +1,42 @@
+name: Build Sphinx docs and deploy to GitHub Pages
+
+# Generate the documentation on all merges to main, all pull requests, or by
+# manual workflow dispatch. The build job can be used as a CI check that the
+# docs still build successfully. The deploy job only runs when a tag is
+# pushed and actually moves the generated html to the gh-pages branch
+# (which triggers a GitHub pages deployment).
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+
+jobs:
+  linting:
+    # scheduled workflows should not run on forks
+    if: (${{ github.event_name == 'schedule' }} && ${{ github.repository_owner == 'SainsburyWellcomeCentre' }} && ${{ github.ref == 'refs/heads/main' }}) || (${{ github.event_name != 'schedule' }})
+    runs-on: ubuntu-latest
+    steps:
+      - uses: neuroinformatics-unit/actions/lint@v2
+
+  build_sphinx_docs:
+    name: Build Sphinx Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: neuroinformatics-unit/actions/build_sphinx_docs@v2
+
+  deploy_sphinx_docs:
+    name: Deploy Sphinx Docs
+    needs: build_sphinx_docs
+    permissions:
+      contents: write
+    if: github.event_name == 'push' && github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@v2
+        with:
+          secret_input: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test_and_deploy.yml

@@ -13,13 +13,13 @@ jobs:
   linting:
     runs-on: ubuntu-latest
     steps:
-      - uses: neuroinformatics-unit/actions/lint@v2.0.0
+      - uses: neuroinformatics-unit/actions/lint@v2
 
   manifest:
     name: Check Manifest
     runs-on: ubuntu-latest
     steps:
-      - uses: neuroinformatics-unit/actions/check_manifest@v2.0.0
+      - uses: neuroinformatics-unit/actions/check_manifest@v2
 
   test:
     needs: [linting, manifest]
@@ -38,29 +38,24 @@ jobs:
             ~/.NeuralPlayground/*
           key: cached-test-data
           enableCrossOsArchive: true
-      - uses: neuroinformatics-unit/actions/test@v2.0.0
+      - uses: neuroinformatics-unit/actions/test@v2
         with:
           python-version: ${{ matrix.python-version }}
-          use-xvfb: true
+          secret-codecov-token: ${{ secrets.CODECOV_TOKEN }}
 
   build_sdist_wheels:
     name: Build source distribution
     needs: [test]
     if: github.event_name == 'push' && github.ref_type == 'tag'
     runs-on: ubuntu-latest
     steps:
-    - uses: neuroinformatics-unit/actions/build_sdist_wheels@v2.0.0
+    - uses: neuroinformatics-unit/actions/build_sdist_wheels@v2
 
   upload_all:
     name: Publish build distributions
     needs: [build_sdist_wheels]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/download-artifact@v3
+    - uses: neuroinformatics-unit/actions/upload_pypi@v2
       with:
-        name: artifact
-        path: dist
-    - uses: pypa/[email protected]
-      with:
-        user: __token__
-        password: ${{ secrets.TWINE_API_KEY }}
+        secret-pypi-key: ${{ secrets.TWINE_API_KEY }}

.gitignore

@@ -62,3 +62,6 @@ coverage.xml
 
 # PyPI distribution / packages
 dist/
+
+# Sphinx documentation
+docs/build/

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
     autoupdate_schedule: monthly
 repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
-      rev: v4.6.0
+      rev: v5.0.0
       hooks:
           - id: check-docstring-first
           - id: check-executables-have-shebangs
@@ -17,7 +17,7 @@ repos:
           - id: trailing-whitespace
             exclude: 'README.md'
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.6.3
+      rev: v0.6.9
       hooks:
         - id: ruff
     - repo: https://github.com/psf/black

MANIFEST.in

@@ -12,3 +12,4 @@ recursive-include documents *.md
 recursive-include neuralplayground *.md
 
 include neuralplayground/vendored/LICENCE_vendored
+recursive-exclude docs *

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

docs/requirements.txt

@@ -0,0 +1,8 @@
+linkify-it-py
+myst-parser
+nbsphinx
+pydata-sphinx-theme
+setuptools-scm
+sphinx
+sphinx-autodoc-typehints
+sphinx-sitemap

docs/source/conf.py

@@ -0,0 +1,122 @@
+# 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 setuptools_scm
+
+# Used when building API docs, put the dependencies
+# of any class you are documenting here
+autodoc_mock_imports = []
+
+# Add the module path to sys.path here.
+# If the directory is relative to the documentation root,
+# use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath("../.."))
+
+project = "NeuralPlayground"
+copyright = "2024, University College London"
+author = "University College London"
+try:
+    release = setuptools_scm.get_version(root="../..", relative_to=__file__)
+except LookupError:
+    # if git is not initialised, still allow local build
+    # with a dummy version
+    release = "0.0.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_sitemap",
+    "myst_parser",
+    "nbsphinx",
+]
+
+# Configure the myst parser to enable cool markdown features
+# See https://sphinx-design.readthedocs.io
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+# Automatically add anchors to markdown headings
+myst_heading_anchors = 3
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# Automatically generate stub pages for API
+autosummary_generate = True
+autodoc_default_flags = ["members", "inherited-members"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "**.ipynb_checkpoints",
+    # to ensure that include files (partial pages) aren't built, exclude them
+    # https://github.com/sphinx-doc/sphinx/issues/1965#issuecomment-124732907
+    "**/includes/**",
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "pydata_sphinx_theme"
+html_title = "NeuralPlayground"
+
+# Customize the theme
+html_theme_options = {
+    "icon_links": [
+        {
+            # Label for this link
+            "name": "GitHub",
+            # URL where the link will redirect
+            "url": "https://github.com/SainsburyWellcomeCentre/NeuralPlayground",  # required
+            # Icon class (if "type": "fontawesome"),
+            # or path to local image (if "type": "local")
+            "icon": "fa-brands fa-github",
+            # The type of image to be used (see below for details)
+            "type": "fontawesome",
+        }
+    ],
+    "logo": {
+        "text": f"{project} v{release}",
+    },
+}
+
+# Redirect the webpage to another URL
+# Sphinx will create the appropriate CNAME file in the build directory
+# The default is the URL of the GitHub pages
+# https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html
+github_user = "SainsburyWellcomeCentre"
+html_baseurl = f"https://{github_user}.github.io/{project}"
+sitemap_url_scheme = "{link}"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']

docs/source/getting_started.md

@@ -0,0 +1,11 @@
+# Getting started
+
+Here you may demonstrate the basic functionalities your package.
+
+You can include code snippets using the usual Markdown syntax:
+
+```python
+from my_package import my_function
+
+result = my_function()
+```

docs/source/index.rst

@@ -0,0 +1,46 @@
+.. NeuralPlayground documentation master file, created by
+   sphinx-quickstart on Fri Dec  9 14:12:42 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to NeuralPlayground's documentation!
+=========================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   getting_started
+   api_index
+
+By default the documentation includes the following sections:
+
+* Getting started. Here you could describe the basic functionalities of your package. To modify this page, edit the file ``docs/source/getting_started.md``.
+* API: here you can find the auto-generated documentation of your package, which is based on the docstrings in your code. To modify which modules/classes/functions are included in the API documentation, edit the file ``docs/source/api_index.rst``.
+
+You can create additional sections with narrative documentation,
+by adding new ``.md`` or ``.rst`` files to the ``docs/source`` folder.
+These files should start with a level-1 (H1) header,
+which will be used as the section title. Sub-sections can be created
+with lower-level headers (H2, H3, etc.) within the same file.
+
+To include a section in the rendered documentation,
+add it to the ``toctree`` directive in this (``docs/source/index.rst``) file.
+
+For example, you could create a ``docs/source/installation.md`` file
+and add it to the ``toctree`` like this:
+
+.. code-block:: rst
+
+   .. toctree::
+      :maxdepth: 2
+      :caption: Contents:
+
+      getting_started
+      installation
+      api_index
+
+Index & Search
+--------------
+* :ref:`genindex`
+* :ref:`search`

examples/comparisons_examples/comparison_examples_score.ipynb

@@ -15,11 +15,11 @@
     "\n",
     "We conduct an autocorrelation analysis of the smoothed spatial rate map. From this analysis, we identified six peaks closest to the central peak and encompassed them within a ring, excluding the central peak. The purpose of this step was to examine the periodicity between these fields . Subsequently, we performed a rotational autocorrelation of this ring and observed the correlations' periodic patterns. To quantify the gridness, we computed a gridness score. This score was determined as the difference between the lowest correlation observed at 60 or 120 degrees of rotation and the highest correlation observed at 30, 90, or 150 degrees of rotation. The results of this analysis are presented as 'gridness measure 1\n",
     "\n",
-    "Generraly a score larger than [0.2] clasify as a grid cell.\n",
+    "Generally a score larger than [0.2] classify as a grid cell.\n",
     "\n",
     "\n",
     " \n",
-    "The code was appadted from:\n",
+    "The code was adapted from:\n",
     "\n",
     "https://github.com/rhayman/ephysiopy/blob/12ee57a858161daa44546b75853a3333097ceb8a/ephysiopy/common/fieldcalcs.py#L743\n",
     "\n",