Merge remote-tracking branch 'upstream/main' into feature/TD-nirs_snirf

* upstream/main: (824 commits)
  Add `psd_args` to `plot_ica_sources` and `ICA.plot_sources` (mne-tools#12912)
  Fix GDF NumPy >= 2 (mne-tools#12909)
  [pre-commit.ci] pre-commit autoupdate (mne-tools#12908)
  ENH: Improve report usability (mne-tools#12901)
  MAINT: Avoid problematic PySide6 (mne-tools#12902)
  Sync README dependencies with pyproject.toml (mne-tools#12890)
  remove trailing slash from pybv base URL [ci skip] (mne-tools#12892)
  Cast tuple of filenames to list to improve error handling (mne-tools#12891)
  Website (mne-tools#12885)
  [pre-commit.ci] pre-commit autoupdate (mne-tools#12888)
  BUG: Fix bugs with coreg (mne-tools#12884)
  Bump mamba-org/setup-micromamba from 1 to 2 in the actions group (mne-tools#12887)
  Update spacing for comments in pyproject.toml (mne-tools#12886)
  make HTML repr for Forward match others (mne-tools#12883)
  MAINT: Linkchecks [circle deploy] (mne-tools#12882)
  Update roadmap (mne-tools#12872)
  [MRG] Require good and bad channels when creating a SpectrumArray object (mne-tools#12877)
  [pre-commit.ci] pre-commit autoupdate (mne-tools#12879)
  MAINT: Update code credit (mne-tools#12880)
  BUG: Fix bug with Path casting (mne-tools#12878)
  ...

.git-blame-ignore-revs

@@ -0,0 +1,16 @@
+# PR number should follow the commit number so that our code credit
+# can parse this file correctly:
+d71e497dcf6f98e19eb81e82e641404a71d2d663  # 1420, split up viz.py
+203a96cbba2732d2e349a8f96065e74bbfd2a53b  # 5862, split utils.py
+ff349f356edb04e1b5f0db13deda8d1a20aca351  # 6767, move around manual parts
+31a83063557fbd54d898f00f9527ffc547888395  # 10407, alphabetize docdict
+e81ec528a42ac687f3d961ed5cf8e25f236925b0  # 11667, black
+12395f9d9cf6ea3c72b225b62e052dd0d17d9889  # 11868, YAML indentation
+d6d2f8c6a2ed4a0b27357da9ddf8e0cd14931b59  # 12097, isort
+e7dd1588013179013a50d3f6b8e8f9ae0a185783  # 12261, ruff format
+940ac9553ce42c15b4c16ecd013824ca3ea7244a  # 12533, whitespace
+e39995d9be6fc831c7a4a59f09b7a7c0a41ae315  # 12588, percent formatting
+1c5b39ff1d99bbcb2fc0e0071a989b3f3845ff30  # 12603, ruff UP028
+b8b168088cb474f27833f5f9db9d60abe00dca83  # 12779, PR JSONs
+ee64eba6f345e895e3d5e7d2804fa6aa2dac2e6d  # 12781, Header unification
+362f9330925fb79a6adc19a42243672676dec63e  # 12799, UP038

.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt  export-subst

.github/CODEOWNERS

@@ -13,10 +13,118 @@
 # This file was adapted from SciPy.
 
 # Each line is a file pattern followed by one or more owners.
+# Syntax follows .gitignore, see https://git-scm.com/docs/gitignore#_pattern_format
 
-# IO
-/mne/io/brainvision @sappelhoff
-/mne/export @sappelhoff
+# Headings ideally should correspond to domains of knowledge/expertise, starting with
+# algorithms implementations (generally main codebase mne/ and related docs) followed by
+# project-level and miscellaneous items (CI, general documentation, etc.).
+
+#################################################
+# Algorithms, implementations, and related docs #
+#################################################
+
+# Artifact regression
+/mne/preprocessing/_regress.py @wmvanvliet
+/mne/preprocessing/tests/test_regress.py @wmvanvliet
 
 # Beamforming
-/mne/beamformer/ @britta-wstnr
+/mne/beamformer @britta-wstnr
+*dics*.py @britta-wstnr @wmvanvliet # related tutorials and examples
+*lcmv*.py @britta-wstnr
+
+# Channels
+/mne/channels @agramfort @mscheltienne @dengemann @jasmainak
+
+# Core sensor-space classes
+/mne/epochs.py @drammock @agramfort @mscheltienne @dengemann
+/mne/evoked.py @drammock @agramfort @mscheltienne @dengemann
+/mne/io/*.* @drammock @cbrnr @agramfort @mscheltienne @dengemann
+
+# Current-source density
+/mne/preprocessing/_csd.py  @alexrockhill @dengemann
+
+# Decoding
+/mne/decoding/csp.py @cbrnr @agramfort @dengemann
+/mne/decoding/*.py @jasmainak
+
+# fNIRS
+/mne/preprocessing/nirs @rob-luke
+*fnirs*.py @rob-luke
+
+# forward
+/mne/forward/ @agramfort @jasmainak
+*forward*.py @agramfort
+
+# Intracranial
+/mne/preprocessing/ieeg @alexrockhill @adam2392
+*seeg*.py @alexrockhill @adam2392
+*ecog*.py @alexrockhill @adam2392
+
+# Inverse Sparse
+/mne/inverse_sparse @agramfort
+*mxne*.py @agramfort # related tutorials and examples
+*gamma*.py @agramfort # related tutorials and examples
+
+# IO
+/mne/io/brainvision @sappelhoff @cbrnr @adam2392
+/mne/io/nirx @rob-luke
+/mne/io/snirf @rob-luke
+/mne/export @sappelhoff @cbrnr
+/mne/io/eeglab.py @jasmainak
+/mne/io/eeglab/tests/test_eeglab.py @jasmainak
+
+# Minimum Norm
+/mne/minimum_norm @agramfort
+
+# Preprocessing
+/mne/preprocessing/ica.py @cbrnr @adam2392 @agramfort @mscheltienne @dengemann
+/mne/preprocessing/infomax_.py @cbrnr @adam2392 @mscheltienne @dengemann
+/mne/preprocessing/*annotate*.py @mscheltienne
+/mne/preprocessing/bads.py @mscheltienne
+/mne/preprocessing/e*g.py @mscheltienne
+
+# Report
+/mne/report @hoechenberger @dengemann @jasmainak
+
+# Simulation
+/mne/simulation/ @agramfort
+*simulate*.py @agramfort
+
+# Surface + transforms
+/mne/surface.py @alexrockhill @larsoner
+/mne/transforms.py @alexrockhill @larsoner
+/mne/_freesurfer.py @alexrockhill @larsoner
+
+# TFR
+/mne/time_frequency @drammock @adam2392 @mscheltienne
+
+# Viz
+/mne/viz @drammock @dengemann
+/mne/viz/_brain @larsoner @wmvanvliet
+/mne/viz/ui_events.py @wmvanvliet
+/tutorials/visualization @larsoner @wmvanvliet @dengemann
+/examples/visualization @larsoner @dengemann
+
+# Datasets
+/mne/datasets/brainstorm @jasmainak
+
+#########################
+# Project-level / other #
+#########################
+
+# Examples and tutorials
+/examples @drammock @agramfort @dengemann
+/tutorials @drammock @agramfort @dengemann
+
+# Non-tutorial documentation text and infrastructure
+/doc @larsoner @drammock @agramfort @dengemann
+/logo @drammock
+
+# Installation documentation
+/doc/install @hoechenberger
+
+# Project infrastructure and CIs
+/*.* @larsoner @drammock  # files in the root directory
+/.circleci @larsoner
+/.github @larsoner
+/tools @larsoner @drammock

.github/CONTRIBUTING.md

@@ -10,4 +10,4 @@ This project and everyone participating in it is governed by the [MNE-Python's C
 
 ## How to contribute
 
-Before contributing make sure you are familiar with [our contributing guide](https://mne.tools/dev/install/contributing.html).
+Before contributing make sure you are familiar with [our contributing guide](https://mne.tools/dev/development/contributing.html).

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -29,8 +29,8 @@ body:
         Paste here a code snippet or minimal working example
         ([MWE](https://en.wikipedia.org/wiki/Minimal_Working_Example))
         to replicate your problem, using one of the
-        [datasets shipped with MNE-Python](https://mne.tools/dev/overview/datasets_index.html),
-        preferably the one called [sample](https://mne.tools/dev/overview/datasets_index.html#sample).
+        [datasets shipped with MNE-Python](https://mne.tools/stable/documentation/datasets.html#datasets),
+        preferably the one called [sample](https://mne.tools/stable/documentation/datasets.html#sample).
       render: Python
     validations:
       required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,7 @@
+<!--
+
 Thanks for contributing a pull request! Please make sure you have read the
-[contribution guidelines](https://mne.tools/dev/install/contributing.html)
+[contribution guidelines](https://mne.tools/dev/development/contributing.html)
 before submitting.
 
 Please be aware that we are a loose team of volunteers so patience is
@@ -11,13 +13,22 @@ case, we ask for your understanding during the review process.
 
 Again, thanks for contributing!
 
-#### Reference issue
-Example: Fixes #1234.
+-->
+
+#### Reference issue (if any)
+
+<!-- Example:
+
+Fixes #1234.
+
+-->
 
 
 #### What does this implement/fix?
-Explain your changes.
+
+<!-- Explain your changes. -->
 
 
 #### Additional information
-Any additional information you think is important.
+
+<!-- Any additional information you think is important. -->

.github/actions/rename_towncrier/rename_towncrier.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+# Adapted from action-towncrier-changelog
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from github import Github
+from tomllib import loads
+
+event_name = os.getenv("GITHUB_EVENT_NAME", "pull_request")
+if not event_name.startswith("pull_request"):
+    print(f"No-op for {event_name}")
+    sys.exit(0)
+if "GITHUB_EVENT_PATH" in os.environ:
+    with open(os.environ["GITHUB_EVENT_PATH"], encoding="utf-8") as fin:
+        event = json.load(fin)
+    pr_num = event["number"]
+    basereponame = event["pull_request"]["base"]["repo"]["full_name"]
+    real = True
+else:  # local testing
+    pr_num = 12318  # added some towncrier files
+    basereponame = "mne-tools/mne-python"
+    real = False
+
+g = Github(os.environ.get("GITHUB_TOKEN"))
+baserepo = g.get_repo(basereponame)
+
+# Grab config from upstream's default branch
+toml_cfg = loads(Path("pyproject.toml").read_text("utf-8"))
+
+config = toml_cfg["tool"]["towncrier"]
+pr = baserepo.get_pull(pr_num)
+modified_files = [f.filename for f in pr.get_files()]
+
+# Get types from config
+types = [ent["directory"] for ent in toml_cfg["tool"]["towncrier"]["type"]]
+type_pipe = "|".join(types)
+
+# Get files that potentially match the types
+directory = toml_cfg["tool"]["towncrier"]["directory"]
+assert directory.endswith("/"), directory
+
+file_re = re.compile(rf"^{directory}({type_pipe})\.rst$")
+found_stubs = [f for f in modified_files if file_re.match(f)]
+for stub in found_stubs:
+    fro = stub
+    to = file_re.sub(rf"{directory}{pr_num}.\1.rst", fro)
+    print(f"Renaming {fro} to {to}")
+    if real:
+        subprocess.check_call(["mv", fro, to])

.github/config.yml

@@ -4,13 +4,13 @@
 
 # Comment to be posted to on first time issues
 newIssueWelcomeComment: >
-  Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴🏽‍♂️
+  Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴
 
 # Configuration for new-pr-welcome - https://github.com/behaviorbot/new-pr-welcome
 
 # Comment to be posted to on PRs from first time contributors in your repository
 newPRWelcomeComment: >
-  Hello! 👋 Thanks for opening your first pull request here! ❤️ We will try to get back to you soon. 🚴🏽‍♂️
+  Hello! 👋 Thanks for opening your first pull request here! ❤️ We will try to get back to you soon. 🚴
 
 # Configuration for first-pr-merge - https://github.com/behaviorbot/first-pr-merge
 

.github/dependabot.yml

@@ -4,3 +4,9 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"
+    labels:
+      - no-changelog-entry-needed

.github/release.yaml

@@ -0,0 +1,6 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot
+      - pre-commit-ci
+      - github-actions

.github/workflows/autofix.yml

@@ -0,0 +1,22 @@
+name: autofix.ci
+
+on:  # yamllint disable-line rule:truthy
+  pull_request:
+    types: [opened, synchronize, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  autofix:
+    name: Autoupdate changelog entry and headers
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install --upgrade towncrier pygithub gitpython numpy
+      - run: python ./.github/actions/rename_towncrier/rename_towncrier.py
+      - run: python ./tools/dev/ensure_headers.py
+      - uses: autofix-ci/action@dd55f44df8f7cdb7a6bf74c78677eb8acd40cd0a

.github/workflows/check_changelog.yml

@@ -0,0 +1,16 @@
+name: Changelog
+
+on:  # yamllint disable-line rule:truthy
+  pull_request:
+    types: [opened, synchronize, labeled, unlabeled]
+    branches: ["main"]
+
+jobs:
+  changelog_checker:
+    name: Check towncrier entry in doc/changes/devel/
+    runs-on: ubuntu-latest
+    steps:
+      - uses: scientific-python/action-towncrier-changelog@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BOT_USERNAME: changelog-bot

.github/workflows/circle_artifacts.yml

@@ -1,14 +1,15 @@
-on: [status]
+on: [status]  # yamllint disable-line rule:truthy
 jobs:
   circleci_artifacts_redirector_job:
     if: "${{ startsWith(github.event.context, 'ci/circleci: build_docs') }}"
     runs-on: ubuntu-20.04
     name: Run CircleCI artifacts redirector
     steps:
       - name: GitHub Action step
-        uses: larsoner/circleci-artifacts-redirector-action@master
+        uses: scientific-python/circleci-artifacts-redirector-action@master
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          artifact-path: 0/dev/index.html
+          api-token: ${{ secrets.CIRCLECI_TOKEN }}
+          artifact-path: 0/html/sg_execution_times.html
           circleci-jobs: build_docs,build_docs_main
           job-title: Check the rendered docs here!