Merge pull request #1144 from sappelhoff/black

MAINT: Use Black for formatting

.circleci/config.yml

@@ -35,6 +35,7 @@ jobs:
 
         - run:
             name: Build the documentation
+            no_output_timeout: 30m
             command: |
               make build-doc
 
@@ -117,6 +118,7 @@ jobs:
 
       - run:
           name: Check links
+          no_output_timeout: 30m
           command: |
             make -C doc linkcheck
 

.git-blame-ignore-revs

@@ -0,0 +1 @@
+58d9cf0b3a916af3e48fbb63b85b699c998c7f7a

.github/workflows/unit_tests.yml

@@ -24,6 +24,7 @@ jobs:
         python-version: ["3.11"]
     steps:
     - uses: actions/checkout@v3
+    - uses: psf/black@stable
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
@@ -35,7 +36,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pydocstyle flake8 check-manifest
+        pip install pydocstyle flake8 check-manifest black
     - name: Display versions and environment information
       run: |
         python --version

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Contributions are welcome in the form of feedback and discussion in issues,
 or pull requests for changes to the code.
 
 Once the implementation of a piece of functionality is considered to be bug
-free and properly documented (both API docs and an example script),
+free and properly documented (both in the API docs and with an example script),
 it can be incorporated into the `main` branch.
 
 To help developing `mne-bids`, you will need a few adjustments to your
@@ -24,10 +24,10 @@ To start with, you should install `mne-bids` as described in our
 [installation documentation](https://mne.tools/mne-bids/dev/install.html).
 For a development environment we recommend that you perform the installation in
 a dedicated Python environment,
-for example using `conda`.
+for example using `conda` (see: https://docs.conda.io/en/latest/miniconda.html).
 Afterwards, a few additional steps need to be performed.
-For all of the steps below we assume that you work in your dedicated `mne-bids`
-Python environment.
+
+**For all of the steps below we assume that you work in your dedicated `mne-bids` Python environment.**
 
 ### Clone MNE-Python and install it from the git repository
 
@@ -37,7 +37,7 @@ then navigate to the cloned repository using the `cd` command.
 Then from the `mne-python` root directory call:
 
 ```Shell
-pip uninstall mne
+pip uninstall mne --yes
 pip install -e .
 ```
 
@@ -54,8 +54,10 @@ Then, `git clone` your fork and install it in "editable" mode.
 git clone https://github.com/<your-GitHub-username>/mne-bids
 cd ./mne-bids
 pip install -e .[full]
+git config --local blame.ignoreRevsFile .git-blame-ignore-revs
 ```
 
+The last command is needed for `git diff` to work properly.
 You should now have both the `mne` and `mne-bids` development versions available in your Python environment.
 
 ### Install additional Python packages required for development
@@ -67,7 +69,7 @@ pip install -r test_requirements.txt
 pip install -r doc/requirements.txt
 ```
 
-This will install several packages to run tests, and build the documentation for `mne-bids`.
+This will install several packages for running tests and building the documentation for `mne-bids`.
 
 ### Install the BIDS validator
 
@@ -119,17 +121,29 @@ figure out how to run the commands without invoking `make`.
 
 We run several style checks on `mne-bids`.
 If you have accurately followed the steps to setup your `mne-bids` development version,
-you can simply call from the root of the `mne-bids` repository:
+you can simply use the following command from the root of the `mne-bids` repository:
 
 ```Shell
 make pep
 ```
 
+We use [Black](https://github.com/psf/black) to format our code.
+You can simply call `black .` from the root of the `mne-bids` repository
+to automatically convert your code to follow the appropriate style.
+
 ## Running tests
 
 We run tests using `pytest`.
+
+First you will need to download the MNE-Python testing data.
+Use the following command:
+
+```Shell
+python -c 'import mne; mne.datasets.testing.data_path(verbose=True)'
+```
+
 If you have accurately followed the steps to setup your `mne-bids` development version,
-you can simply call from the root of the `mne-bids` repository:
+you can then simply use the following command from the root of the `mne-bids` repository:
 
 ```Shell
 make test
@@ -146,7 +160,7 @@ VALIDATOR_EXECUTABLE=../bids-validator/bids-validator/bin/bids-validator pytest
 
 The documentation can be built using [Sphinx](https://www.sphinx-doc.org).
 If you have accurately followed the steps to setup your `mne-bids` development version,
-you can simply call from the root of the `mne-bids` repository:
+you can simply use the following command from the root of the `mne-bids` repository:
 
 ```Shell
 make build-doc

MANIFEST.in

@@ -23,6 +23,7 @@ exclude tools
 prune .circleci
 prune paper
 
+exclude .git-blame-ignore-revs
 exclude CITATION.cff
 exclude Makefile
 exclude CONTRIBUTING.md

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all clean-pyc clean-so clean-build clean-ctags clean-cache clean-e clean inplace test check-manifest flake pydocstyle pep build-doc dist-build
+.PHONY: all clean-pyc clean-so clean-build clean-ctags clean-cache clean-e clean inplace test check-manifest flake black pydocstyle pep build-doc dist-build
 
 all: clean inplace pep test build-doc dist-build
 
@@ -45,11 +45,15 @@ flake:
 	@echo "Running flake8"
 	@flake8 --count mne_bids examples
 
+black:
+	@echo "Running black"
+	@black --check .
+
 pydocstyle:
 	@echo "Running pydocstyle"
 	@pydocstyle .
 
-pep: flake pydocstyle check-manifest
+pep: flake pydocstyle check-manifest black
 
 build-doc:
 	@echo "Building documentation"