[MAINT] Add CI checks, update linting, docs, and config (#7)

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/unit_tests.yml

@@ -0,0 +1,92 @@
+name: "unit_tests"
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.type }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "*"
+
+jobs:
+  # Run unit tests
+  test_pip:
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash -e {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.10"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: macos-13  # Intel
+            python-version: "3.12"
+          - os: macos-14  # arm64
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+    env:
+      TZ: Europe/Berlin
+      FORCE_COLOR: true
+      DISPLAY: ":99.0"
+      OPENBLAS_NUM_THREADS: "1"
+      PYTHONUNBUFFERED: "1"
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/checkout@v4
+      - uses: pyvista/setup-headless-display-action@main
+        with:
+          qt: true
+          pyvista: false
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install --upgrade --upgrade-strategy eager .[test]
+      - name: Display versions and environment information
+        run: |
+          echo $TZ
+          date
+          python --version
+          which python
+      - run: pip install -e .
+      - run: python -c "import pyparrm; print(f'PyPARRM {pyparrm.__version__}')"
+      - name: Run pytest
+        run: python -m coverage run && coverage report
+
+  test_conda:
+    timeout-minutes: 90
+    runs-on: ubuntu-20.04
+    defaults:
+      run:
+        shell: bash -el {0}
+    env:
+      MKL_NUM_THREADS: '1'
+      PYTHONUNBUFFERED: '1'
+      PYTHON_VERSION: '3.12'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pyvista/setup-headless-display-action@main
+        with:
+          qt: true
+          pyvista: false
+      - uses: mamba-org/setup-micromamba@v1
+        with:
+          environment-file: environment.yml
+          create-args: >- # beware the >- instead of |, we don't split on newlines but on spaces
+            python=${{ env.PYTHON_VERSION }}
+      - name: Install package and test dependencies
+        run: |
+          pip install -e .
+          pip install .[test]
+      - name: Display version information
+        run: python -c "import pyparrm; print(f'PyPARRM {pyparrm.__version__}')"
+      - name: Run pytest
+        run: python -m coverage run && coverage report

.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+repos:
+  # ruff PyPARRM
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.7
+    hooks:
+      - id: ruff
+        name: ruff lint pyparrm
+        args: ["--fix"]
+        files: ^src/pyparrm/
+
+  # ruff examples
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.7
+    hooks:
+      - id: ruff
+        name: ruff lint examples
+        args: ["--fix"]
+        files: ^examples/
+
+  # codespell
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+        files: ^pyparrm/|^docs/|^examples/
+        types_or: [python, rst, inc]
+
+  # yamllint
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.35.1
+    hooks:
+      - id: yamllint
+        args: [--strict, -c, .yamllint.yml]
+
+  # rstcheck
+  - repo: https://github.com/rstcheck/rstcheck.git
+    rev: v6.2.0
+    hooks:
+      - id: rstcheck
+        additional_dependencies:
+          - tomli
+        files: ^docs/.*\.(rst|inc)$
+
+  # toml-sort
+  - repo: https://github.com/pappasam/toml-sort.git
+    rev: v0.23.1
+    hooks:
+      - id: toml-sort-fix
+
+ci:
+  autofix_prs: true

.readthedocs.yaml

@@ -13,13 +13,14 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/source/conf.py
-   builder: html
-   fail_on_warning: false
+  configuration: docs/source/conf.py
+  builder: html
+  fail_on_warning: false
 
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - method: pip
-     path: .
-   - requirements: requirements_rtd.txt
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc

.yamllint.yml

@@ -0,0 +1,8 @@
+extends: default
+
+rules:
+  line-length: disable
+  document-start: disable
+  truthy: disable
+  new-lines:
+    type: platform

changelog.md

@@ -1,6 +1,6 @@
 # PyPARRM Changelog
 
-## [Version 1.1.1dev](https://pyparrm.readthedocs.io/en/main/index.html)
+## [Version 1.2.0dev](https://pyparrm.readthedocs.io/en/main/index.html)
 
 ##### Enhancements
 - Updated test coverage.

docs/make.bat

@@ -8,6 +8,8 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
+set AUTOEXDIR=%SOURCEDIR%\auto_examples
+set GENDIR=%SOURCEDIR%\generated
 set BUILDDIR=build
 
 %SPHINXBUILD% >NUL 2>NUL
@@ -24,12 +26,20 @@ if errorlevel 9009 (
 )
 
 if "%1" == "" goto help
+if "%1" == "clean" goto clean
 
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:clean
+echo Removing everything under '%AUTOEXDIR%' and '%GENDIR%'...
+del /S /Q %AUTOEXDIR%\* >nul 2>&1
+del /S /Q %GENDIR%\* >nul 2>&1
+%SPHINXBUILD% -M clean %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd

docs/source/_static/versions.json

@@ -1,7 +1,7 @@
 [
     {
-        "name": "1.1.1dev",
-        "version": "1.1.1dev",
+        "name": "1.2.0dev",
+        "version": "1.2.0dev",
         "url": "https://pyparrm.readthedocs.io/en/main/"
     },
     {

docs/source/_templates/custom-module-template.rst

@@ -60,8 +60,8 @@
     :toctree:
     :template: custom-module-template.rst
     :recursive:
-{% for item in modules %}
-    {{ item }}
-{%- endfor %}
-{% endif %}
-{% endblock %}
+    {% for item in modules %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

docs/source/api.rst

@@ -1,6 +1,8 @@
 API
 ===
 
+Here are the API references for PyPARRM.
+
 .. container:: d-none
 
     :py:mod:`pyparrm`:

docs/source/conf.py

@@ -33,6 +33,7 @@
     "numpydoc",
     "sphinxcontrib.bibtex",
     "sphinx_gallery.gen_gallery",
+    "sphinx_copybutton",
 ]
 
 source_suffix = [".rst", ".md"]

docs/source/development.rst

@@ -10,52 +10,52 @@ View the changelog for each PyPARRM version here: `version changelog
 Installing PyPARRM in editable mode
 -----------------------------------
 
-If you want to make changes to PyPARRM, you may wish to install it in editable
-mode. To do so, first clone the `GitHub repository
-<https://github.com/neuromodulation/pyparrm/tree/main>`_ to your desired
-location. Once cloned, navigate to this location and install the package
-alongside its development requirements using pip:
+If you want to make changes to PyPARRM, you may wish to install it in editable mode.
+To do so, first clone the `GitHub repository
+<https://github.com/neuromodulation/PyPARRM/tree/main>`_ to your desired location. Once
+cloned, navigate to this location and install the package alongside its development
+requirements using pip:
 
-.. code-block:: console
+.. code-block::
     
-    $ pip install -e .
-    $ pip install pybispectra[dev]
+    pip install -e .
+    pip install .[dev]
 
 
 Contributing to PyPARRM
 -----------------------
 
-If you encounter any issues with the package or wish to suggest improvements,
-please submit a report on the `issues page
-<https://github.com/neuromodulation/pyparrm/issues>`_.
+If you encounter any issues with the package or wish to suggest improvements, please
+submit a report on the `issues page <https://github.com/braindatalab/PyPARRM/issues>`_.
 
-If you have made any changes which you would like to see officially added to
-the package, consider submitting a `pull request
-<https://github.com/neuromodulation/pyparrm/pulls>`_. When submitting a pull
-request, please check that the existing test suite passes, and if you add new
-features, please make sure that these are covered in the unit tests. The tests
-can be run by calling `coverage <https://coverage.readthedocs.io/en/>`_ with
-`pytest <https://docs.pytest.org/en/>`_ in the base directory:
+If you have made any changes which you would like to see officially added to the
+package, consider submitting a `pull request
+<https://github.com/braindatalab/PyPARRM/pulls>`_. A unit test suite is included.
+Tests must be added for any new features, and adaptations to the existing tests must be
+made where necessary. Checks for these tests are run when a pull request is submitted,
+however these tests can also be run locally by calling `coverage
+<https://coverage.readthedocs.io/en/>`_ with `pytest <https://docs.pytest.org/en/>`_ in
+the base directory:
 
-.. code-block:: console
+.. code-block::
     
-    $ coverage run --source=pyparrm -m pytest -v tests && coverage report -m
+    coverage run && coverage report
 
-Please also check that the documentation can be built following any changes,
-which can be done using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in
-the ``/docs`` directory:
+Please also check that the documentation can be built following any changes. The
+documentation is built when a pull request is submitted, however the documentation can
+also be built locally using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in the
+``/docs`` directory (outputs are in the ``/docs/build/html`` directory):
 
-.. code-block:: console
+.. code-block::
     
-    $ make html
+    make html
 
-Finally, features of the code such as compliance with established styles and
-spelling errors in the documentation are also checked. Please ensure that the
-code is formatted using `Black <https://black.readthedocs.io/en/stable/>`_, and
-check that there are no egregious errors from the following commands:
+Finally, features of the code such as compliance with established styles and spelling
+errors in the documentation are also checked. These checks are run when a pull request
+is submitted, however they can also be run locally using `pre-commit
+<https://pre-commit.com/>`_. To have these checks run automatically whenever you commit
+changes, install ``pre-commit`` with the following command in the base directory:
 
-.. code-block:: console
+.. code-block::
     
-    $ flake8
-    $ pydocstyle
-    $ codespell
+    pre-commit install

docs/source/examples.rst

@@ -1,7 +1,7 @@
 Examples
 ========
 
-Find out how to get started with the package using the provided examples:
+Find out how to get started with PyPARRM using the provided examples.
 
 .. toctree::
    :maxdepth: 1