Merge branch 'main' into installer

.pre-commit-config.yaml

@@ -7,15 +7,15 @@ repos:
 
   # Ruff mne
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.291
+    rev: v0.0.292
     hooks:
       - id: ruff
         name: ruff mne
         files: ^mne/
 
   # Ruff tutorials and examples
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.291
+    rev: v0.0.292
     hooks:
       - id: ruff
         name: ruff tutorials and examples
@@ -26,7 +26,7 @@ repos:
 
   # Codespell
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.5
+    rev: v2.2.6
     hooks:
       - id: codespell
         additional_dependencies:

doc/conf.py

@@ -1591,6 +1591,32 @@ def reset_warnings(gallery_conf, fname):
     "xdawn_denoising.py",
     "xhemi.py",
 }
+api_redirects = {
+    "connectivity",
+    "covariance",
+    "creating_from_arrays",
+    "datasets",
+    "decoding",
+    "events",
+    "export",
+    "file_io",
+    "forward",
+    "inverse",
+    "logging",
+    "most_used_classes",
+    "mri",
+    "preprocessing",
+    "python_reference",
+    "reading_raw_data",
+    "realtime",
+    "report",
+    "sensor_space",
+    "simulation",
+    "source_space",
+    "statistics",
+    "time_frequency",
+    "visualization",
+}
 ex = "auto_examples"
 co = "connectivity"
 mne_conn = "https://mne.tools/mne-connectivity/stable"
@@ -1609,36 +1635,39 @@ def reset_warnings(gallery_conf, fname):
 custom_redirects = {
     # Custom redirects (one HTML path to another, relative to outdir)
     # can be added here as fr->to key->value mappings
+    "install/contributing.html": "development/contributing.html",
+    "overview/roadmap.html": "development/roadmap.html",
+    "whats_new.html": "development/whats_new.html",
     f"{tu}/evoked/plot_eeg_erp.html": f"{tu}/evoked/30_eeg_erp.html",
     f"{tu}/evoked/plot_whitened.html": f"{tu}/evoked/40_whitened.html",
-    f"{tu}/misc/plot_modifying_data_inplace.html": f"{tu}/intro/15_inplace.html",  # noqa E501
+    f"{tu}/misc/plot_modifying_data_inplace.html": f"{tu}/intro/15_inplace.html",
     f"{tu}/misc/plot_report.html": f"{tu}/intro/70_report.html",
     f"{tu}/misc/plot_seeg.html": f"{tu}/clinical/20_seeg.html",
     f"{tu}/misc/plot_ecog.html": f"{tu}/clinical/30_ecog.html",
     f"{tu}/{ml}/plot_receptive_field.html": f"{tu}/{ml}/30_strf.html",
     f"{tu}/{ml}/plot_sensors_decoding.html": f"{tu}/{ml}/50_decoding.html",
     f"{tu}/{sm}/plot_background_freesurfer.html": f"{tu}/{fw}/10_background_freesurfer.html",  # noqa E501
-    f"{tu}/{sm}/plot_source_alignment.html": f"{tu}/{fw}/20_source_alignment.html",  # noqa E501
+    f"{tu}/{sm}/plot_source_alignment.html": f"{tu}/{fw}/20_source_alignment.html",
     f"{tu}/{sm}/plot_forward.html": f"{tu}/{fw}/30_forward.html",
     f"{tu}/{sm}/plot_eeg_no_mri.html": f"{tu}/{fw}/35_eeg_no_mri.html",
     f"{tu}/{sm}/plot_background_freesurfer_mne.html": f"{tu}/{fw}/50_background_freesurfer_mne.html",  # noqa E501
-    f"{tu}/{sm}/plot_fix_bem_in_blender.html": f"{tu}/{fw}/80_fix_bem_in_blender.html",  # noqa E501
-    f"{tu}/{sm}/plot_compute_covariance.html": f"{tu}/{fw}/90_compute_covariance.html",  # noqa E501
-    f"{tu}/{sm}/plot_object_source_estimate.html": f"{tu}/{nv}/10_stc_class.html",  # noqa E501
+    f"{tu}/{sm}/plot_fix_bem_in_blender.html": f"{tu}/{fw}/80_fix_bem_in_blender.html",
+    f"{tu}/{sm}/plot_compute_covariance.html": f"{tu}/{fw}/90_compute_covariance.html",
+    f"{tu}/{sm}/plot_object_source_estimate.html": f"{tu}/{nv}/10_stc_class.html",
     f"{tu}/{sm}/plot_dipole_fit.html": f"{tu}/{nv}/20_dipole_fit.html",
     f"{tu}/{sm}/plot_mne_dspm_source_localization.html": f"{tu}/{nv}/30_mne_dspm_loreta.html",  # noqa E501
     f"{tu}/{sm}/plot_dipole_orientations.html": f"{tu}/{nv}/35_dipole_orientations.html",  # noqa E501
     f"{tu}/{sm}/plot_mne_solutions.html": f"{tu}/{nv}/40_mne_fixed_free.html",
-    f"{tu}/{sm}/plot_beamformer_lcmv.html": f"{tu}/{nv}/50_beamformer_lcmv.html",  # noqa E501
+    f"{tu}/{sm}/plot_beamformer_lcmv.html": f"{tu}/{nv}/50_beamformer_lcmv.html",
     f"{tu}/{sm}/plot_visualize_stc.html": f"{tu}/{nv}/60_visualize_stc.html",
     f"{tu}/{sm}/plot_eeg_mri_coords.html": f"{tu}/{nv}/70_eeg_mri_coords.html",
     f"{tu}/{sd}/plot_brainstorm_phantom_elekta.html": f"{tu}/{nv}/80_brainstorm_phantom_elekta.html",  # noqa E501
     f"{tu}/{sd}/plot_brainstorm_phantom_ctf.html": f"{tu}/{nv}/85_brainstorm_phantom_ctf.html",  # noqa E501
     f"{tu}/{sd}/plot_phantom_4DBTi.html": f"{tu}/{nv}/90_phantom_4DBTi.html",
-    f"{tu}/{sd}/plot_brainstorm_auditory.html": f"{tu}/io/60_ctf_bst_auditory.html",  # noqa E501
+    f"{tu}/{sd}/plot_brainstorm_auditory.html": f"{tu}/io/60_ctf_bst_auditory.html",
     f"{tu}/{sd}/plot_sleep.html": f"{tu}/clinical/60_sleep.html",
     f"{tu}/{di}/plot_background_filtering.html": f"{tu}/preprocessing/25_background_filtering.html",  # noqa E501
-    f"{tu}/{di}/plot_background_statistics.html": f"{tu}/{sn}/10_background_stats.html",  # noqa E501
+    f"{tu}/{di}/plot_background_statistics.html": f"{tu}/{sn}/10_background_stats.html",
     f"{tu}/{sn}/plot_stats_cluster_erp.html": f"{tu}/{sn}/20_erp_stats.html",
     f"{tu}/{sn}/plot_stats_cluster_1samp_test_time_frequency.html": f"{tu}/{sn}/40_cluster_1samp_time_freq.html",  # noqa E501
     f"{tu}/{sn}/plot_stats_cluster_time_frequency.html": f"{tu}/{sn}/50_cluster_between_time_freq.html",  # noqa E501
@@ -1649,10 +1678,10 @@ def reset_warnings(gallery_conf, fname):
     f"{tu}/{sr}/plot_stats_cluster_time_frequency_repeated_measures_anova.html": f"{tu}/{sn}/70_cluster_rmANOVA_time_freq.html",  # noqa E501
     f"{tu}/{tf}/plot_sensors_time_frequency.html": f"{tu}/{tf}/20_sensors_time_frequency.html",  # noqa E501
     f"{tu}/{tf}/plot_ssvep.html": f"{tu}/{tf}/50_ssvep.html",
-    f"{tu}/{si}/plot_creating_data_structures.html": f"{tu}/{si}/10_array_objs.html",  # noqa E501
+    f"{tu}/{si}/plot_creating_data_structures.html": f"{tu}/{si}/10_array_objs.html",
     f"{tu}/{si}/plot_point_spread.html": f"{tu}/{si}/70_point_spread.html",
     f"{tu}/{si}/plot_dics.html": f"{tu}/{si}/80_dics.html",
-    f"{tu}/{tf}/plot_eyetracking.html": f"{tu}/preprocessing/90_eyetracking_data.html",  # noqa E501
+    f"{tu}/{tf}/plot_eyetracking.html": f"{tu}/preprocessing/90_eyetracking_data.html",
     f"{ex}/{co}/mne_inverse_label_connectivity.html": f"{mne_conn}/{ex}/mne_inverse_label_connectivity.html",  # noqa E501
     f"{ex}/{co}/cwt_sensor_connectivity.html": f"{mne_conn}/{ex}/cwt_sensor_connectivity.html",  # noqa E501
     f"{ex}/{co}/mixed_source_space_connectivity.html": f"{mne_conn}/{ex}/mixed_source_space_connectivity.html",  # noqa E501
@@ -1661,11 +1690,21 @@ def reset_warnings(gallery_conf, fname):
     f"{ex}/{co}/mne_inverse_envelope_correlation_volume.html": f"{mne_conn}/{ex}/mne_inverse_envelope_correlation_volume.html",  # noqa E501
     f"{ex}/{co}/mne_inverse_envelope_correlation.html": f"{mne_conn}/{ex}/mne_inverse_envelope_correlation.html",  # noqa E501
     f"{ex}/{co}/mne_inverse_psi_visual.html": f"{mne_conn}/{ex}/mne_inverse_psi_visual.html",  # noqa E501
-    f"{ex}/{co}/sensor_connectivity.html": f"{mne_conn}/{ex}/sensor_connectivity.html",  # noqa E501
-    f"{ex}/{vi}/publication_figure.html": f"{tu}/{vi}/10_publication_figure.html",  # noqa E501
+    f"{ex}/{co}/sensor_connectivity.html": f"{mne_conn}/{ex}/sensor_connectivity.html",
+    f"{ex}/{vi}/publication_figure.html": f"{tu}/{vi}/10_publication_figure.html",
 }
 
 
+def check_existing_redirect(path):
+    """Make sure existing HTML files are redirects, before overwriting."""
+    if os.path.isfile(path):
+        with open(path, "r") as fid:
+            for _ in range(8):
+                next(fid)
+            line = fid.readline()
+            assert "Page Redirection" in line, line
+
+
 def make_redirects(app, exception):
     """Make HTML redirects."""
     # https://www.sphinx-doc.org/en/master/extdev/appapi.html
@@ -1675,7 +1714,6 @@ def make_redirects(app, exception):
         and exception is None
     ):
         return
-    logger = sphinx.util.logging.getLogger("mne")
     TEMPLATE = """\
 <!DOCTYPE HTML>
 <html lang="en-US">
@@ -1715,25 +1753,30 @@ def make_redirects(app, exception):
         sphinx_logger.info(
             f"Added {len(fnames):3d} HTML plot_* redirects for {out_dir}"
         )
+    # API redirects
+    for page in api_redirects:
+        fname = f"{page}.html"
+        fr_path = os.path.join(app.outdir, fname)
+        to_path = os.path.join(app.outdir, "api", fname)
+        # allow overwrite if existing file is just a redirect
+        check_existing_redirect(fr_path)
+        with open(fr_path, "w") as fid:
+            fid.write(TEMPLATE.format(to=to_path))
+    sphinx_logger.info(f"Added {len(api_redirects):3d} HTML API redirects")
     # custom redirects
     for fr, to in custom_redirects.items():
         if not to.startswith("http"):
             assert os.path.isfile(os.path.join(app.outdir, to)), to
             # handle links to sibling folders
             path_parts = to.split("/")
-            assert tu in path_parts, path_parts  # need to refactor otherwise
-            path_parts = [".."] + path_parts[(path_parts.index(tu) + 1) :]
+            if tu in path_parts:
+                path_parts = [".."] + path_parts[(path_parts.index(tu) + 1) :]
             to = os.path.join(*path_parts)
         assert to.endswith("html"), to
         fr_path = os.path.join(app.outdir, fr)
         assert fr_path.endswith("html"), fr_path
         # allow overwrite if existing file is just a redirect
-        if os.path.isfile(fr_path):
-            with open(fr_path, "r") as fid:
-                for _ in range(8):
-                    next(fid)
-                line = fid.readline()
-                assert "Page Redirection" in line, line
+        check_existing_redirect(fr_path)
         # handle folders that no longer exist
         if fr_path.split("/")[-2] in (
             "misc",
@@ -1755,7 +1798,6 @@ def make_version(app, exception):
         and exception is None
     ):
         return
-    logger = sphinx.util.logging.getLogger("mne")
     try:
         stdout, _ = run_subprocess(["git", "rev-parse", "HEAD"], verbose=False)
     except Exception as exc:

doc/overview/development.rst → doc/development/index.rst

@@ -29,7 +29,7 @@ experience.
 .. toctree::
    :hidden:
 
-   ../install/contributing
-   ../whats_new
+   contributing
+   whats_new
    roadmap
    governance

doc/development/whats_new.rst

@@ -0,0 +1,42 @@
+.. _whats_new:
+
+What's new
+==========
+
+Changes for each version of MNE-Python are listed below.
+
+.. toctree::
+   :maxdepth: 1
+
+   ../changes/devel.rst
+   ../changes/v1.5.rst
+   ../changes/v1.4.rst
+   ../changes/v1.3.rst
+   ../changes/v1.2.rst
+   ../changes/v1.1.rst
+   ../changes/v1.0.rst
+   ../changes/v0.24.rst
+   ../changes/v0.23.rst
+   ../changes/v0.22.rst
+   ../changes/v0.21.rst
+   ../changes/v0.20.rst
+   ../changes/v0.19.rst
+   ../changes/v0.18.rst
+   ../changes/v0.17.rst
+   ../changes/v0.16.rst
+   ../changes/v0.15.rst
+   ../changes/v0.14.rst
+   ../changes/v0.13.rst
+   ../changes/v0.12.rst
+   ../changes/v0.11.rst
+   ../changes/v0.10.rst
+   ../changes/v0.9.rst
+   ../changes/v0.8.rst
+   ../changes/v0.7.rst
+   ../changes/v0.6.rst
+   ../changes/v0.5.rst
+   ../changes/v0.4.rst
+   ../changes/v0.3.rst
+   ../changes/v0.2.rst
+   ../changes/v0.1.rst
+   ../old_versions/index.rst

doc/overview/cookbook.rst → doc/documentation/cookbook.rst

@@ -13,7 +13,7 @@ References below refer to Python functions and objects.
 
 .. _flow_diagram:
 
-.. figure:: images/flow_diagram.svg
+.. figure:: ../_static/flow_diagram.svg
     :alt: MNE Workflow Flowchart
     :align: center
 

doc/overview/index.rst → doc/documentation/index.rst

@@ -7,7 +7,7 @@ Documentation overview
 
    If you haven't already installed MNE-Python, please take a look
    at our :ref:`installation guides<installers>`. Please also kindly find some
-   resources for :doc:`learn_python` if you need to.
+   resources for :doc:`../help/learn_python` if you need to.
 
 
 The documentation for MNE-Python is divided into four main sections:
@@ -24,12 +24,12 @@ The documentation for MNE-Python is divided into four main sections:
    how a particular technique you've read about can be applied using
    MNE-Python.
 
-3. The :doc:`../glossary` provides short definitions of MNE-Python-specific
+3. The :doc:`glossary` provides short definitions of MNE-Python-specific
    vocabulary and general neuroimaging concepts. The glossary is often a good
    place to look if you don't understand a term or acronym used somewhere else
    in the documentation.
 
-4. The :doc:`API reference <../python_reference>` provides documentation for
+4. The :doc:`API reference <../api/python_reference>` provides documentation for
    the classes, functions and methods in the MNE-Python codebase. This is the
    same information that is rendered when running
    :samp:`help(mne.{<function_name>})` in an interactive Python session, or
@@ -42,20 +42,20 @@ categories above) are shown in the navigation menu, including the
 :ref:`implementation details<implementation>`, and more.
 Documentation for the related C and MATLAB tools are available here:
 
-- :ref:`MNE-MATLAB <mne_matlab>` (HTML)
+- `MNE-MATLAB`_ (repository)
 - `MNE-C <MNE-C manual_>`_ (PDF)
 
 .. toctree::
    :hidden:
 
    Tutorials<../auto_tutorials/index>
    Examples<../auto_examples/index>
-   ../glossary
+   glossary
    Implementation details<implementation>
    design_philosophy
-   Example datasets<datasets_index>
+   Example datasets<datasets>
    Command-line tools<../generated/commands>
-   migrating
+   ../help/migrating
    cookbook
    cite
-   ../cited
+   cited

doc/index.rst

@@ -35,7 +35,7 @@ MNE-Python Homepage
    :hidden:
 
    Install <install/index>
-   Documentation <overview/index>
-   API Reference <python_reference>
-   Get help <overview/get_help>
-   Development <overview/development>
+   Documentation <documentation/index>
+   API Reference <api/python_reference>
+   Get help <help/index>
+   Development <development/index>

doc/install/advanced.rst

@@ -102,47 +102,6 @@ just prefer to use git rather than pip to make frequent updates, there are
 instructions for installing from a ``git clone`` in the :ref:`contributing`.
 
 
-.. _other-py-distros:
-
-Other Python distributions
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-While the `Anaconda`_ Python distribution provides many conveniences, other
-distributions of Python should also work with MNE-Python.  In particular,
-`Miniconda`_ is a lightweight alternative to Anaconda that is fully compatible;
-like Anaconda, Miniconda includes the ``conda`` command line tool for
-installing new packages and managing environments; unlike Anaconda, Miniconda
-starts off with a minimal set of around 30 packages instead of Anaconda's
-hundreds. See the `installation instructions for Miniconda`_ for more info.
-A similar alternative is `MiniForge`_, which uses the ``conda-forge`` channel
-as the default source for package installation (saving you the trouble of
-typing ``--channel=conda-forge`` with each ``conda install`` command).
-
-.. warning::
-
-    If you have the ``PYTHONPATH`` or ``PYTHONHOME`` environment variables set,
-    you may run into difficulty using Anaconda. See the
-    `Anaconda troubleshooting guide`_ for more information. Note that it is
-    easy to switch between ``conda``-managed Python installations and the
-    system Python installation using the ``conda activate`` and ``conda
-    deactivate`` commands, so you may find that after adopting Anaconda it is
-    possible (indeed, preferable) to leave ``PYTHONPATH`` and ``PYTHONHOME``
-    permanently unset.
-
-
-It is also possible to use a system-level installation of Python (version
-|min_python_version| or higher) and use ``pip`` to install MNE-Python and its
-dependencies, using the provided `requirements file`_:
-
-.. code-block:: console
-
-    $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/requirements.txt
-    $ pip install --user -r requirements.txt
-
-Other configurations will probably also work, but we may be unable to offer
-support if you encounter difficulties related to your particular Python
-installation choices.
-
 .. _CUDA:
 
 GPU acceleration with CUDA