diff --git a/.codespell.rc b/.codespell.rc new file mode 100644 index 0000000..5aa9aba --- /dev/null +++ b/.codespell.rc @@ -0,0 +1,2 @@ +[codespell] +skip = .git,*.pdf,*.svg,./docs/build diff --git a/.github/workflows/docs_build_and_deploy.yml b/.github/workflows/docs_build_and_deploy.yml index 1ebfe4d..85d3aae 100644 --- a/.github/workflows/docs_build_and_deploy.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 289cfee..aedc8d7 100644 --- a/.gitignore +++ b/.gitignore @@ -81,4 +81,3 @@ venv/ # written by setuptools_scm **/_version.py - diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..71f9f50 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 63291be..6af1a92 100644 --- a/README.md +++ b/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). \ No newline at end of file +This repository hosts the source code for the [SWC-Blueprint website](https://swc-blueprint.neuroinformatics.dev). diff --git a/docs/make.bat b/docs/make.bat index 747ffb7..dc1312a 100644 --- a/docs/make.bat +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 0afab10..e6f6522 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -sphinx -pydata-sphinx-theme +linkify-it-py myst-parser -sphinx-design -numpydoc nbsphinx -linkify-it-py \ No newline at end of file +numpydoc +pydata-sphinx-theme +sphinx +sphinx-design diff --git a/docs/source/index.md b/docs/source/index.md index 5792982..365a75d 100644 --- a/docs/source/index.md +++ b/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 -``` \ No newline at end of file +``` diff --git a/docs/source/specification.md b/docs/source/specification.md index 8ea9f80..32e50f7 100644 --- a/docs/source/specification.md +++ b/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,20 +32,20 @@ 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 @@ -53,8 +53,8 @@ Below we describe each level of the `rawdata` folder hierarchy in more detail. T ### 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/