From 6683f56cfa20ce0f188f6e2377596bae0491bf34 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Tue, 30 May 2023 12:55:15 +0200 Subject: [PATCH] add info to contrib guide; update makefile --- .circleci/config.yml | 2 ++ CONTRIBUTING.md | 30 +++++++++++++++++++++--------- Makefile | 8 ++++++-- doc/conf.py | 2 +- doc/sphinxext/gen_cli.py | 3 +-- 5 files changed, 31 insertions(+), 14 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 992391aa5..e1f39ce38 100644 --- a/.circleci/config.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6dc0c7375..612b1c041 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/Makefile b/Makefile index ea33b4c38..c3deb90f9 100755 --- a/Makefile +++ b/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" diff --git a/doc/conf.py b/doc/conf.py index 84c454010..e1b003df8 100644 --- a/doc/conf.py +++ b/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), diff --git a/doc/sphinxext/gen_cli.py b/doc/sphinxext/gen_cli.py index 683434894..d2a35c8f8 100644 --- a/doc/sphinxext/gen_cli.py +++ b/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: