MAINT: Use Black for formatting

.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:

CONTRIBUTING.md

@@ -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

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

doc/conf.py

@@ -13,32 +13,32 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 curdir = os.path.dirname(__file__)
-sys.path.append(os.path.abspath(os.path.join(curdir, '..', 'mne_bids')))
-sys.path.append(os.path.abspath(os.path.join(curdir, 'sphinxext')))
+sys.path.append(os.path.abspath(os.path.join(curdir, "..", "mne_bids")))
+sys.path.append(os.path.abspath(os.path.join(curdir, "sphinxext")))
 
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = '2.0'
+needs_sphinx = "2.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.githubpages',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx_gallery.gen_gallery',
-    'numpydoc',
-    'sphinx_copybutton',
-    'gen_cli',  # custom extension, see ./sphinxext/gen_cli.py
-    'gh_substitutions',  # custom extension, see ./sphinxext/gh_substitutions.py
+    "sphinx.ext.githubpages",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx_gallery.gen_gallery",
+    "numpydoc",
+    "sphinx_copybutton",
+    "gen_cli",  # custom extension, see ./sphinxext/gen_cli.py
+    "gh_substitutions",  # custom extension, see ./sphinxext/gh_substitutions.py
 ]
 
 # configure sphinx-copybutton
@@ -50,51 +50,52 @@
 numpydoc_class_members_toctree = False
 numpydoc_attributes_as_param_list = True
 numpydoc_xref_aliases = {
-    'BIDSPath': ':class:`BIDSPath <mne_bids.BIDSPath>`',
-    'path-like': ':term:`path-like <mne:path-like>`',
-    'array-like': ':term:`array_like <numpy:array_like>`',
-    'int': ':class:`int <python:int>`',
-    'bool': ':class:`bool <python:bool>`',
-    'float': ':class:`float <python:float>`',
-    'list': ':class:`list <python:list>`',
-    'tuple': ':class:`tuple <python:tuple>`',
-    'NibabelImageObject': 'nibabel.spatialimages.SpatialImage',
+    "BIDSPath": ":class:`BIDSPath <mne_bids.BIDSPath>`",
+    "path-like": ":term:`path-like <mne:path-like>`",
+    "array-like": ":term:`array_like <numpy:array_like>`",
+    "int": ":class:`int <python:int>`",
+    "bool": ":class:`bool <python:bool>`",
+    "float": ":class:`float <python:float>`",
+    "list": ":class:`list <python:list>`",
+    "tuple": ":class:`tuple <python:tuple>`",
+    "NibabelImageObject": "nibabel.spatialimages.SpatialImage",
 }
 numpydoc_xref_ignore = {
     # words
-    'instance', 'instances', 'of'
+    "instance",
+    "instances",
+    "of",
 }
 
 
 # generate autosummary even if no references
 autosummary_generate = True
-autodoc_default_options = {'inherited-members': None}
-default_role = 'autolink'  # XXX silently allows bad syntax, someone should fix
+autodoc_default_options = {"inherited-members": None}
+default_role = "autolink"  # XXX silently allows bad syntax, someone should fix
 
 # configure linkcheck
 # https://sphinx-doc.org/en/master/usage/configuration.html?#options-for-the-linkcheck-builder
 linkcheck_retries = 2
 linkcheck_rate_limit_timeout = 15.0
 linkcheck_ignore = [
-    r'https://www.researchgate.net/profile/.*',
+    r"https://www.researchgate.net/profile/.*",
 ]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'MNE-BIDS'
+project = "MNE-BIDS"
 td = date.today()
-copyright = u'2017-%s, MNE Developers. Last updated on %s' % (td.year,
-                                                              td.isoformat())
+copyright = "2017-%s, MNE Developers. Last updated on %s" % (td.year, td.isoformat())
 
-author = u'MNE Developers'
+author = "MNE Developers"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -108,39 +109,42 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['auto_examples/index.rst', '_build', 'Thumbs.db',
-                    '.DS_Store']
+exclude_patterns = ["auto_examples/index.rst", "_build", "Thumbs.db", ".DS_Store"]
 
 # HTML options (e.g., theme)
 html_show_sourcelink = False
 html_copy_source = False
 
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-html_static_path = ['_static']
-html_css_files = ['style.css']
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+html_css_files = ["style.css"]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 switcher_version_match = "dev" if "dev" in release else version
 html_theme_options = {
-    'icon_links': [
-        dict(name='GitHub',
-             url='https://github.com/mne-tools/mne-bids',
-             icon='fab fa-github-square'),
-        dict(name='Discourse',
-             url='https://mne.discourse.group/tags/mne-bids',
-             icon='fab fa-discourse'),
+    "icon_links": [
+        dict(
+            name="GitHub",
+            url="https://github.com/mne-tools/mne-bids",
+            icon="fab fa-github-square",
+        ),
+        dict(
+            name="Discourse",
+            url="https://mne.discourse.group/tags/mne-bids",
+            icon="fab fa-discourse",
+        ),
     ],
-    'icon_links_label': 'Quick Links',  # for screen reader
-    'use_edit_page_button': False,
-    'navigation_with_keys': False,
-    'show_toc_level': 1,
-    'navbar_end': ['theme-switcher', 'version-switcher', 'navbar-icon-links'],
-    'analytics': dict(google_analytics_id='G-C8SH9E98QC'),
+    "icon_links_label": "Quick Links",  # for screen reader
+    "use_edit_page_button": False,
+    "navigation_with_keys": False,
+    "show_toc_level": 1,
+    "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
+    "analytics": dict(google_analytics_id="G-C8SH9E98QC"),
     "switcher": {
         "json_url": "https://raw.githubusercontent.com/mne-tools/mne-bids/main/doc/_static/versions.json",  # noqa: E501
         "version_match": switcher_version_match,
@@ -156,15 +160,15 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
-    'mne': ('https://mne.tools/dev', None),
-    '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),
-    'nilearn': ('http://nilearn.github.io/stable', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/dev', None),
-    'nibabel': ('https://nipy.org/nibabel', None),
+    "python": ("https://docs.python.org/3", None),
+    "mne": ("https://mne.tools/dev", None),
+    "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),
+    "nilearn": ("http://nilearn.github.io/stable", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
+    "nibabel": ("https://nipy.org/nibabel", None),
 }
 intersphinx_timeout = 5
 
@@ -174,31 +178,31 @@
 # instead of in the root."
 # we will store dev docs in a `dev` subdirectory and all other docs in a
 # directory "v" + version_str. E.g., "v0.3"
-if 'dev' in version:
-    filepath_prefix = 'dev'
+if "dev" in version:
+    filepath_prefix = "dev"
 else:
-    filepath_prefix = 'v{}'.format(version)
+    filepath_prefix = "v{}".format(version)
 
 sphinx_gallery_conf = {
-    'doc_module': 'mne_bids',
-    'reference_url': {
-        'mne_bids': None,
+    "doc_module": "mne_bids",
+    "reference_url": {
+        "mne_bids": None,
     },
-    'backreferences_dir': 'generated',
-    'examples_dirs': '../examples',
-    'within_subsection_order': ExampleTitleSortKey,
-    'gallery_dirs': 'auto_examples',
-    'filename_pattern': '^((?!sgskip).)*$',
-    'binder': {
+    "backreferences_dir": "generated",
+    "examples_dirs": "../examples",
+    "within_subsection_order": ExampleTitleSortKey,
+    "gallery_dirs": "auto_examples",
+    "filename_pattern": "^((?!sgskip).)*$",
+    "binder": {
         # Required keys
-        'org': 'mne-tools',
-        'repo': 'mne-bids',
-        'branch': 'gh-pages',  # noqa: E501 Can be any branch, tag, or commit hash. Use a branch that hosts your docs.
-        'binderhub_url': 'https://mybinder.org',  # noqa: E501 Any URL of a binderhub deployment. Must be full URL (e.g. https://mybinder.org).
-        'filepath_prefix': filepath_prefix,  # noqa: E501 A prefix to prepend to any filepaths in Binder links.
-        'dependencies': [
-            '../test_requirements.txt',
-            './requirements.txt',
+        "org": "mne-tools",
+        "repo": "mne-bids",
+        "branch": "gh-pages",  # noqa: E501 Can be any branch, tag, or commit hash. Use a branch that hosts your docs.
+        "binderhub_url": "https://mybinder.org",  # noqa: E501 Any URL of a binderhub deployment. Must be full URL (e.g. https://mybinder.org).
+        "filepath_prefix": filepath_prefix,  # noqa: E501 A prefix to prepend to any filepaths in Binder links.
+        "dependencies": [
+            "../test_requirements.txt",
+            "./requirements.txt",
         ],
-    }
+    },
 }

doc/sphinxext/gen_cli.py

@@ -20,7 +20,7 @@
 
 def setup(app):
     """Set up the app."""
-    app.connect('builder-inited', generate_cli_rst)
+    app.connect("builder-inited", generate_cli_rst)
 
 
 # Header markings go:
@@ -58,57 +58,65 @@ def setup(app):
 
 def generate_cli_rst(app=None):
     """Generate the command line interface docs."""
-    out_dir = op.abspath(op.join(op.dirname(__file__), '..', 'generated'))
+    out_dir = op.abspath(op.join(op.dirname(__file__), "..", "generated"))
     if not op.isdir(out_dir):
         os.mkdir(out_dir)
-    out_fname = op.join(out_dir, 'cli.rst.new')
+    out_fname = op.join(out_dir, "cli.rst.new")
 
     cli_path = op.abspath(
-        op.join(os.path.dirname(__file__), '..', '..', 'mne_bids', 'commands'))
-    fnames = sorted([
-        op.basename(fname)
-        for fname in glob.glob(op.join(cli_path, 'mne_bids*.py'))])
+        op.join(os.path.dirname(__file__), "..", "..", "mne_bids", "commands")
+    )
+    fnames = sorted(
+        [op.basename(fname) for fname in glob.glob(op.join(cli_path, "mne_bids*.py"))]
+    )
     iterator = sphinx.util.status_iterator(
-        fnames, 'generating MNE-BIDS cli help ... ', length=len(fnames))
-    with open(out_fname, 'w', encoding='utf-8') as f:
+        fnames, "generating MNE-BIDS cli help ... ", length=len(fnames)
+    )
+    with open(out_fname, "w", encoding="utf-8") as f:
         f.write(header)
         for fname in iterator:
             cmd_name = fname[:-3]
             run_name = op.join(cli_path, fname)
-            output, _ = run_subprocess([sys.executable, run_name, '--help'],
-                                       verbose=False)
+            output, _ = run_subprocess(
+                [sys.executable, run_name, "--help"], verbose=False
+            )
             output = output.splitlines()
 
             # Swap usage and title lines
             output[0], output[2] = output[2], output[0]
 
             # Add header marking
             for idx in (1, 0):
-                output.insert(idx, '-' * len(output[0]))
+                output.insert(idx, "-" * len(output[0]))
 
             # Add code styling for the "Usage: " line
             for li, line in enumerate(output):
-                if line.startswith('Usage: mne_bids '):
-                    output[li] = 'Usage: ``%s``' % line[7:]
+                if line.startswith("Usage: mne_bids "):
+                    output[li] = "Usage: ``%s``" % line[7:]
                     break
 
             # Turn "Options:" into field list
-            if 'Options:' in output:
-                ii = output.index('Options:')
-                output[ii] = 'Options'
-                output.insert(ii + 1, '-------')
-                output.insert(ii + 2, '')
-                output.insert(ii + 3, '.. rst-class:: field-list cmd-list')
-                output.insert(ii + 4, '')
-            output = '\n'.join(output)
-            f.write(command_rst % (cmd_name,
-                                   cmd_name.replace('mne_bids_', 'mne_bids '),
-                                   '=' * len(cmd_name),
-                                   output))
+            if "Options:" in output:
+                ii = output.index("Options:")
+                output[ii] = "Options"
+                output.insert(ii + 1, "-------")
+                output.insert(ii + 2, "")
+                output.insert(ii + 3, ".. rst-class:: field-list cmd-list")
+                output.insert(ii + 4, "")
+            output = "\n".join(output)
+            f.write(
+                command_rst
+                % (
+                    cmd_name,
+                    cmd_name.replace("mne_bids_", "mne_bids "),
+                    "=" * len(cmd_name),
+                    output,
+                )
+            )
     _replace_md5(out_fname)
-    print('[Done]')
+    print("[Done]")
 
 
 # This is useful for testing/iterating to see what the result looks like
-if __name__ == '__main__':
+if __name__ == "__main__":
     generate_cli_rst()