add pre-commit checks including codespell (#33)

.codespell.rc

@@ -0,0 +1,2 @@
+[codespell]
+skip = .git,*.pdf,*.svg,./docs/build

.github/workflows/docs_build_and_deploy.yml

@@ -15,8 +15,20 @@ on:
   workflow_dispatch:
 
 jobs:
+  codespell:
+    name: Check for spelling errors
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2
+
   build_sphinx_docs:
     name: Build Sphinx Docs
+    needs: codespell
     runs-on: ubuntu-latest
     steps:
       - uses: neuroinformatics-unit/actions/build_sphinx_docs@v2

.gitignore

@@ -81,4 +81,3 @@ venv/
 
 # written by setuptools_scm
 **/_version.py
-

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+exclude: 'conf.py'
+
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v4.3.0
+      hooks:
+          - id: check-docstring-first
+          - id: check-executables-have-shebangs
+          - id: check-merge-conflict
+          - id: check-toml
+          - id: end-of-file-fixer
+          - id: mixed-line-ending
+            args: [--fix=lf]
+          - id: requirements-txt-fixer
+          - id: trailing-whitespace
+    - repo: https://github.com/codespell-project/codespell
+      rev: v2.2.5
+      hooks:
+      - id: codespell

README.md

@@ -6,8 +6,8 @@
 
 The [SWC-Blueprint specification](specification.md) provides a set of rules and guidelines for project folder organisation, ensuring consistent data management within and between labs. The focus is on ensuring minimal overhead for researchers.
 
-`SWC-Blueprint` is being developed at the [Sainsbury Wellcome Centre (SWC) for Neural Circuits and Behaviour](https://www.sainsburywellcome.org/) by members of the [Neuroinformatics Unit (NIU)](https://neuroinformatics.dev/). As such, it prioritizes interoperability with NIU-developed data analysis tools. 
+`SWC-Blueprint` is being developed at the [Sainsbury Wellcome Centre (SWC) for Neural Circuits and Behaviour](https://www.sainsburywellcome.org/) by members of the [Neuroinformatics Unit (NIU)](https://neuroinformatics.dev/). As such, it prioritizes interoperability with NIU-developed data analysis tools.
 
 That said, the specification is designed to be as general as possible, and should be useful to anyone within the neuroscience field. We (the NIU) welcome [feedback](https://github.com/neuroinformatics-unit/SWC-Blueprint/discussions) and contributions from the wider community and commit to maintaining the specification as a living and evolving document. We will also collaborate with [ongoing efforts](https://github.com/INCF/neuroscience-data-structure) by the [INCF](https://www.incf.org/) and [BIDS community](https://bids.neuroimaging.io/) to extend the BIDS specification to non-human animal research.
 
-This repository hosts the source code for the [SWC-Blueprint website](https://swc-blueprint.neuroinformatics.dev).
+This repository hosts the source code for the [SWC-Blueprint website](https://swc-blueprint.neuroinformatics.dev).

docs/make.bat

@@ -1,35 +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
+@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

@@ -1,7 +1,7 @@
-sphinx
-pydata-sphinx-theme
+linkify-it-py
 myst-parser
-sphinx-design
-numpydoc
 nbsphinx
-linkify-it-py
+numpydoc
+pydata-sphinx-theme
+sphinx
+sphinx-design

docs/source/index.md

@@ -7,7 +7,7 @@
 
 The [SWC-Blueprint specification](specification.md) provides a set of rules and guidelines for project folder organisation, ensuring consistent data management within and between labs. The focus is on ensuring minimal overhead for researchers.
 
-**SWC-Blueprint** is being developed at the [Sainsbury Wellcome Centre (SWC) for Neural Circuits and Behaviour](https://www.sainsburywellcome.org/) by members of the [Neuroinformatics Unit (NIU)](https://neuroinformatics.dev/). As such, it prioritizes interoperability with NIU-developed data analysis tools. 
+**SWC-Blueprint** is being developed at the [Sainsbury Wellcome Centre (SWC) for Neural Circuits and Behaviour](https://www.sainsburywellcome.org/) by members of the [Neuroinformatics Unit (NIU)](https://neuroinformatics.dev/). As such, it prioritizes interoperability with NIU-developed data analysis tools.
 
 That said, the specification is designed to be as general as possible, and should be useful to anyone within the neuroscience field. We (the NIU) welcome [feedback](https://github.com/neuroinformatics-unit/SWC-Blueprint/discussions) and contributions from the wider community and commit to maintaining the specification as a living and evolving document. We will also collaborate with [ongoing efforts](https://github.com/INCF/neuroscience-data-structure) by the [INCF](https://www.incf.org/) and [BIDS community](https://bids.neuroimaging.io/) to extend the BIDS specification to non-human animal research.
 
@@ -16,4 +16,4 @@ That said, the specification is designed to be as general as possible, and shoul
 :caption: Contents
 
 specification
-```
+```

docs/source/specification.md

@@ -7,7 +7,7 @@ In addition, it also includes some non-mandatory conventions for [naming files](
 We mark requirements with italicised *keywords* that should be interpreted as described by the [Network Working Group](https://www.ietf.org/rfc/rfc2119.txt). In decreasing order of requirement, these are: *must* {octicon}`alert;1em;sd-text-danger`, *should* {octicon}`info;1em;sd-text-warning`, and *may* {octicon}`check-circle;1em;sd-text-success`.
 :::
 
-## Project folder structure 
+## Project folder structure
 
 Standardised project folders contain data that are hierarchically structured according to the [BIDS standard](https://bids-specification.readthedocs.io/en/stable/02-common-principles.html).
 
@@ -20,9 +20,9 @@ For example:
 
 * The project folder *may* have any name descriptive of the project, but it *must* be without spaces.
 
-* Within the project folder, data *must* be separated into `rawdata` and `derivatives`. 
+* Within the project folder, data *must* be separated into `rawdata` and `derivatives`.
 
-  * `rawdata`: coming out of the data acquisition system (e.g. binary files, tiffs, videos files). 
+  * `rawdata`: coming out of the data acquisition system (e.g. binary files, tiffs, videos files).
 
   * `derivatives`: any processed data that is derived from `rawdata` (e.g. spike sorting or pose estimation).
 
@@ -32,29 +32,29 @@ For example:
 
 * Datatype folder names *must* be one of the following : `ephys`, `behav`, `funcimg`, `histology`.
 
-* If collected, `ephys`, `behav`, `funcimg` *must* be placed under the session level. If collected, `histology` *must* be placed under the subject level. 
+* If collected, `ephys`, `behav`, `funcimg` *must* be placed under the session level. If collected, `histology` *must* be placed under the subject level.
 
 Below we describe each level of the `rawdata` folder hierarchy in more detail. Though we impose no absolute requirements for the folder structure within `derivatives`, it *should* match the hierarchy in `rawdata` whenever possible.
 
 ### Subject
 
-* Each subject *must* have exactly one subject-level folder. 
-* Subject-level folders *must* be prefixed with a key-value pair that is unique for each subject. The key *must* be `sub` and the value *must* be numerical, e.g. `sub-001`. 
+* Each subject *must* have exactly one subject-level folder.
+* Subject-level folders *must* be prefixed with a key-value pair that is unique for each subject. The key *must* be `sub` and the value *must* be numerical, e.g. `sub-001`.
 * Subjects *should* be assigned ascending numerical labels as they are added to the project. The labels *should* be prefixed with an arbitrary number of 0s for consistent indentation and sorting, e.g. `sub-001`, `sub-002`, `sub-003`.
 * Additional key-value pairs with alphanumerical labels *may* be appended after the `sub` key-value pair. For example, animal IDs (e.g. from the animal facility) can be added as follows: `sub-001_id-5645332`. The keys *should* be consistent across subjects.
 
 :::{hint}
 * valid: `sub-02`, `sub-001_id-5645332_sex-F`, `sub-02_species-mouse`
-* invalid: 
+* invalid:
   * `mouse-01`: the first key should have been `sub`.
   * `sub-001_female`: `female` should have been written as a key-value pair (e.g. `sex-female`)
   * `sub-B`: the `sub` key should have a numerical value
 :::
 
 ### Session
 
-* Each session *must* have exactly one session-level folder. 
-* Session-level folders *must* be prefixed with a key-value pair that is unique for each session. The key *must* be `ses` and the value *must* be numerical, e.g. `ses-01`. 
+* Each session *must* have exactly one session-level folder.
+* Session-level folders *must* be prefixed with a key-value pair that is unique for each session. The key *must* be `ses` and the value *must* be numerical, e.g. `ses-01`.
 * Sessions *should* be assigned ascending numerical labels as they are added to the project. The labels *should* be prefixed with an arbitrary number of 0s for consistent indentation and sorting, e.g. `ses-01`, `ses-02`, `ses-03`.
 * Additional key-value pairs with alphanumerical labels *may* be appended after the `ses` key-value pair. For example, dates can be added as follows: `ses-001_date-20230310`. The keys *should* be consistent across subjects.
 * If a date field is added, it *should* be in the format `YYYYMMDD`.
@@ -93,8 +93,8 @@ A real project folder might look like:
     │       │   │   ├── sub-001_ses-01_recording-01.bin
     │       │   │   └── sub-001_ses-01_probe-3A.imec0
     │       │   └── behav/
-    │       │       ├── sub-001_ses-01_camera-01.wav 
-    │       │       └── sub-001_ses-01_data-responses.csv 
+    │       │       ├── sub-001_ses-01_camera-01.wav
+    │       │       └── sub-001_ses-01_data-responses.csv
     │       └── histology/
     │           └── sub-001_image-brain.tiff
     └── derivatives/