add info to contrib guide; update makefile

.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
 

.github/workflows/unit_tests.yml

@@ -36,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 .
 ```
 
@@ -69,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
 
@@ -121,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
@@ -148,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

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"

doc/conf.py

@@ -165,7 +165,7 @@
     "mne-gui-addons": ("https://mne.tools/mne-gui-addons", None),
     "numpy": ("https://numpy.org/devdocs", None),
     "scipy": ("https://scipy.github.io/devdocs", None),
-    "matplotlib": ("https://matplotlib.org", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
     "nilearn": ("http://nilearn.github.io/stable", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
     "nibabel": ("https://nipy.org/nibabel", None),

doc/sphinxext/gen_cli.py

@@ -11,7 +11,6 @@
 import os
 import glob
 from os import path as op
-import subprocess
 import sys
 
 import sphinx.util
@@ -69,7 +68,7 @@ def generate_cli_rst(app=None):
     fnames = sorted(
         [op.basename(fname) for fname in glob.glob(op.join(cli_path, "mne_bids*.py"))]
     )
-    iterator = sphinx.util.status_iterator(
+    iterator = sphinx.util.display.status_iterator(
         fnames, "generating MNE-BIDS cli help ... ", length=len(fnames)
     )
     with open(out_fname, "w", encoding="utf-8") as f: