From d0f986b0d7d7a29cc187835c02c0f21d68d67540 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Mon, 17 Aug 2026 15:15:08 -0400 Subject: [PATCH] Speed up doc build by reworking links --- doc/_includes/bem_model.rst | 2 +- doc/api/mri.rst | 4 +- doc/changes/dev.rst | 2 + doc/changes/dev.rst.template | 2 + doc/changes/v0.1.rst | 2 + doc/changes/v0.10.rst | 2 + doc/changes/v0.11.rst | 2 + doc/changes/v0.12.rst | 4 + doc/changes/v0.13.rst | 6 +- doc/changes/v0.14.rst | 2 + doc/changes/v0.15.rst | 2 + doc/changes/v0.16.rst | 2 + doc/changes/v0.17.rst | 6 +- doc/changes/v0.18.rst | 2 + doc/changes/v0.19.rst | 2 + doc/changes/v0.2.rst | 2 + doc/changes/v0.20.rst | 2 + doc/changes/v0.21.rst | 2 + doc/changes/v0.22.rst | 2 + doc/changes/v0.23.rst | 2 + doc/changes/v0.24.rst | 2 + doc/changes/v0.3.rst | 2 + doc/changes/v0.4.rst | 2 + doc/changes/v0.5.rst | 2 + doc/changes/v0.6.rst | 2 + doc/changes/v0.7.rst | 2 + doc/changes/v0.8.rst | 2 + doc/changes/v0.9.rst | 2 + doc/changes/v1.0.rst | 2 + doc/changes/v1.1.rst | 2 + doc/changes/v1.10.rst | 2 + doc/changes/v1.11.rst | 2 + doc/changes/v1.12.rst | 2 + doc/changes/v1.2.rst | 4 + doc/changes/v1.3.rst | 2 + doc/changes/v1.4.rst | 2 + doc/changes/v1.5.rst | 2 + doc/changes/v1.6.rst | 2 + doc/changes/v1.7.rst | 8 +- doc/changes/v1.8.rst | 6 +- doc/changes/v1.9.rst | 4 +- doc/conf.py | 17 ++- doc/credits/index.rst | 2 + doc/credits/leaders.rst | 6 +- doc/credits/sponsors.rst | 4 +- doc/development/contributing.rst | 22 ++-- doc/development/index.rst | 6 +- doc/development/roadmap.rst | 12 +- doc/documentation/datasets.rst | 7 +- doc/help/faq.rst | 10 +- doc/help/index.rst | 2 + doc/help/learn_python.rst | 2 +- doc/install/advanced.rst | 12 +- doc/install/check_installation.rst | 5 +- doc/install/ides.rst | 10 +- doc/install/installers.rst | 2 + doc/install/manual_install_python.rst | 6 +- doc/install/mne_c.rst | 3 +- doc/links.inc | 86 ++----------- doc/sphinxext/mne_doc_utils.py | 120 ++++++++++++++++++ examples/datasets/limo_data.py | 1 - examples/decoding/decoding_csp_eeg.py | 4 +- examples/io/read_xdf.py | 3 +- examples/visualization/brain.py | 2 + mne/bem.py | 9 +- tutorials/clinical/30_ecog.py | 2 +- tutorials/forward/20_source_alignment.py | 5 +- .../forward/50_background_freesurfer_mne.py | 2 +- .../40_artifact_correction_ica.py | 3 +- .../stats-sensor-space/10_background_stats.py | 10 +- 70 files changed, 327 insertions(+), 156 deletions(-) diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index cb9c849c1bb..580b84f0029 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -17,7 +17,7 @@ Using the watershed algorithm The watershed algorithm [Segonne *et al.*, 2004] is part of the FreeSurfer software. -The name of the program is mri_watershed_. +The name of the program is `mri_watershed `__. Its use in the MNE environment is facilitated by the script :ref:`mne watershed_bem`. diff --git a/doc/api/mri.rst b/doc/api/mri.rst index 6cd38cbbeb4..265aa540acd 100644 --- a/doc/api/mri.rst +++ b/doc/api/mri.rst @@ -9,7 +9,7 @@ Step by step instructions for using :func:`gui.coregistration`: - `Coregistration for subjects with structural MRI `_ - `Scaling a template MRI for subjects for which no MRI is available - `_ + `__ See also: @@ -39,3 +39,5 @@ See also: transforms.compute_volume_registration vertex_to_mni coreg.Coregistration + +.. include:: ../links.inc diff --git a/doc/changes/dev.rst b/doc/changes/dev.rst index 0e80d522b51..1d5cee9b84f 100644 --- a/doc/changes/dev.rst +++ b/doc/changes/dev.rst @@ -3,3 +3,5 @@ .. _current: .. towncrier-draft-entries:: Version |release| (development) + +.. include:: names.inc diff --git a/doc/changes/dev.rst.template b/doc/changes/dev.rst.template index 0e80d522b51..1d5cee9b84f 100644 --- a/doc/changes/dev.rst.template +++ b/doc/changes/dev.rst.template @@ -3,3 +3,5 @@ .. _current: .. towncrier-draft-entries:: Version |release| (development) + +.. include:: names.inc diff --git a/doc/changes/v0.1.rst b/doc/changes/v0.1.rst index 3d60006d497..f75677ce1e4 100644 --- a/doc/changes/v0.1.rst +++ b/doc/changes/v0.1.rst @@ -16,3 +16,5 @@ of commits): * 41 Emily Ruzich * 2 Martin Luessi * 9 Matti Hämäläinen + +.. include:: names.inc diff --git a/doc/changes/v0.10.rst b/doc/changes/v0.10.rst index 34cc0673baf..b23c4ab7c36 100644 --- a/doc/changes/v0.10.rst +++ b/doc/changes/v0.10.rst @@ -146,3 +146,5 @@ The committer list for this release is the following (preceded by number of comm * 3 Daniel McCloy * 3 Daniel Strohmeier * 1 Jussi Nurminen + +.. include:: names.inc diff --git a/doc/changes/v0.11.rst b/doc/changes/v0.11.rst index 218508e86fb..32d44926d27 100644 --- a/doc/changes/v0.11.rst +++ b/doc/changes/v0.11.rst @@ -90,3 +90,5 @@ The committer list for this release is the following (preceded by number of comm * 2 emilyps14 * 2 lennyvarghese * 1 Marian Dovgialo + +.. include:: names.inc diff --git a/doc/changes/v0.12.rst b/doc/changes/v0.12.rst index b48b80bf2d0..f472672a968 100644 --- a/doc/changes/v0.12.rst +++ b/doc/changes/v0.12.rst @@ -209,3 +209,7 @@ The committer list for this release is the following (preceded by number of comm * 1 pbnsilva * 1 sviter * 1 zuxfoucault + +.. include:: names.inc + +.. include:: ../links.inc diff --git a/doc/changes/v0.13.rst b/doc/changes/v0.13.rst index 0571d737b0c..a0621ff40f9 100644 --- a/doc/changes/v0.13.rst +++ b/doc/changes/v0.13.rst @@ -150,7 +150,7 @@ API 5. Previously, if the filter was as long or longer than the signal of interest, direct FFT-based computations were used. Now a single code path (overlap-add filtering) is used for all FIR filters. This could cause minor changes in how short signals are filtered. -- Support for Python 2.6 has been dropped, and the minimum supported dependencies are NumPy_ 1.8, SciPy_ 0.12, and Matplotlib_ 1.3 by `Eric Larson`_ +- Support for Python 2.6 has been dropped, and the minimum supported dependencies are `NumPy `__ 1.8, `SciPy `__ 0.12, and Matplotlib_ 1.3 by `Eric Larson`_ - When CTF gradient compensation is applied to raw data, it is no longer reverted on save of :meth:`mne.io.Raw.save` by `Eric Larson`_ @@ -246,3 +246,7 @@ The committer list for this release is the following (sorted by alphabetical ord * Simon-Shlomo Poil * Teon Brooks * Yaroslav Halchenko + +.. include:: names.inc + +.. include:: ../links.inc diff --git a/doc/changes/v0.14.rst b/doc/changes/v0.14.rst index bfb9498a0c1..3cafced6a2c 100644 --- a/doc/changes/v0.14.rst +++ b/doc/changes/v0.14.rst @@ -248,3 +248,5 @@ People who contributed to this release (in alphabetical order): * Stefan Repplinger * Teon Brooks * Yaroslav Halchenko + +.. include:: names.inc diff --git a/doc/changes/v0.15.rst b/doc/changes/v0.15.rst index d72833b9f08..cd838147f76 100644 --- a/doc/changes/v0.15.rst +++ b/doc/changes/v0.15.rst @@ -327,3 +327,5 @@ People who contributed to this release (in alphabetical order): * Simon Kern * Teon Brooks * Yousra Bekhti + +.. include:: names.inc diff --git a/doc/changes/v0.16.rst b/doc/changes/v0.16.rst index cdf6dbf0495..0b01aae4d3b 100644 --- a/doc/changes/v0.16.rst +++ b/doc/changes/v0.16.rst @@ -256,3 +256,5 @@ People who contributed to this release (in alphabetical order): * Stefan Repplinger * Tommy Clausner * Yaroslav Halchenko + +.. include:: names.inc diff --git a/doc/changes/v0.17.rst b/doc/changes/v0.17.rst index 49e722c584d..10b1623f39f 100644 --- a/doc/changes/v0.17.rst +++ b/doc/changes/v0.17.rst @@ -50,7 +50,7 @@ Changelog - Add helmet for Artemis123 for :func:`mne.viz.plot_alignment` by `Eric Larson`_ -- Add support for reading MATLAB ``v7.3+`` files in :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` via `pymatreader`_ by `Steven Gutstein`_, `Eric Larson`_, and `Thomas Hartmann`_ +- Add support for reading MATLAB ``v7.3+`` files in :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab` via `pymatreader `__ by `Steven Gutstein`_, `Eric Larson`_, and `Thomas Hartmann`_ - Add support for raw PSD plots in :meth:`mne.Report.parse_folder` via ``raw_psd`` argument of :class:`mne.Report` by `Eric Larson`_ @@ -315,3 +315,7 @@ People who contributed to this release (in alphabetical order): * Tristan Stenner * buildqa * jeythekey + +.. include:: names.inc + +.. include:: ../links.inc diff --git a/doc/changes/v0.18.rst b/doc/changes/v0.18.rst index e70bbb68233..34bcf634fc8 100644 --- a/doc/changes/v0.18.rst +++ b/doc/changes/v0.18.rst @@ -266,3 +266,5 @@ API - The peak finder that was formerly accessible via ``from mne.preprocessing.peak_finder import peak_finder`` should now be imported directly from the enclosing namespace as ``from mne.preprocessing import peak_finder`` by `Eric Larson`_ - Deprecate ``mne.realtime`` module to make a standalone module ``mne-realtime`` that will live outside of this package by `Teon Brooks`_ + +.. include:: names.inc diff --git a/doc/changes/v0.19.rst b/doc/changes/v0.19.rst index 5e34210868a..fee3592a2ef 100644 --- a/doc/changes/v0.19.rst +++ b/doc/changes/v0.19.rst @@ -230,3 +230,5 @@ API - Reading annotations contained in GDF files with :func:`mne.io.read_raw_gdf` now returns numeric event codes as descriptions (instead of textual descriptions) due to restrictive licensing of the GDF event code table from BioSig by `Clemens Brunner`_ - ``channels.find_ch_connectivity`` now returns pre-built neighbor maps for KIT systems when available, by `Christian Brodbeck`_ + +.. include:: names.inc diff --git a/doc/changes/v0.2.rst b/doc/changes/v0.2.rst index 528e2a64f88..ca2973c5bee 100644 --- a/doc/changes/v0.2.rst +++ b/doc/changes/v0.2.rst @@ -38,3 +38,5 @@ of commits): * 12 Martin Luessi * 2 Yaroslav Halchenko * 1 Manfred Kitzbichler + +.. include:: names.inc diff --git a/doc/changes/v0.20.rst b/doc/changes/v0.20.rst index b50eea64fed..4b3e5a69a31 100644 --- a/doc/changes/v0.20.rst +++ b/doc/changes/v0.20.rst @@ -405,3 +405,5 @@ People who contributed to this release (in alphabetical order): * Thomas Hartmann * Victor Férat * Yu-Han Luo + +.. include:: names.inc diff --git a/doc/changes/v0.21.rst b/doc/changes/v0.21.rst index ce191ecbad4..598fc2c6535 100644 --- a/doc/changes/v0.21.rst +++ b/doc/changes/v0.21.rst @@ -472,3 +472,5 @@ People who contributed to this release in alphabetical order * Yu-Han Luo * chapochn * mshader + +.. include:: names.inc diff --git a/doc/changes/v0.22.rst b/doc/changes/v0.22.rst index 67e76f3db0a..88e746e04e4 100644 --- a/doc/changes/v0.22.rst +++ b/doc/changes/v0.22.rst @@ -251,3 +251,5 @@ People who contributed to this release in alphabetical order * Thomas Hartmann * Tod Flak + * Victoria Peterson + + +.. include:: names.inc diff --git a/doc/changes/v0.23.rst b/doc/changes/v0.23.rst index 73eee5c13d2..ac27462bd9b 100644 --- a/doc/changes/v0.23.rst +++ b/doc/changes/v0.23.rst @@ -366,3 +366,5 @@ People who contributed to this release in alphabetical order * Victoria Peterson * Yu-Han Luo * Zhi Zhang+ + +.. include:: names.inc diff --git a/doc/changes/v0.24.rst b/doc/changes/v0.24.rst index 21459ad96b6..53db6d87c37 100644 --- a/doc/changes/v0.24.rst +++ b/doc/changes/v0.24.rst @@ -394,3 +394,5 @@ People who contributed to this release in alphabetical order * Timothy Gates+ * Valerii Chirkov * Xiaokai Xia+ + +.. include:: names.inc diff --git a/doc/changes/v0.3.rst b/doc/changes/v0.3.rst index 9c61d8c482b..c1c5d5808e4 100644 --- a/doc/changes/v0.3.rst +++ b/doc/changes/v0.3.rst @@ -38,3 +38,5 @@ of commits): * 80 Alexandre Gramfort * 51 Martin Luessi + +.. include:: names.inc diff --git a/doc/changes/v0.4.rst b/doc/changes/v0.4.rst index 680e5fe8123..f922238a801 100644 --- a/doc/changes/v0.4.rst +++ b/doc/changes/v0.4.rst @@ -50,3 +50,5 @@ of commits): * 4 Christian Brodbeck * 4 Louis Thibault * 2 Brad Buran + +.. include:: names.inc diff --git a/doc/changes/v0.5.rst b/doc/changes/v0.5.rst index 9d6a8b3b856..df85f33c258 100644 --- a/doc/changes/v0.5.rst +++ b/doc/changes/v0.5.rst @@ -123,3 +123,5 @@ of commits): * 6 Daniel Strohmeier * 4 Teon Brooks * 1 Dan G. Wakeman + +.. include:: names.inc diff --git a/doc/changes/v0.6.rst b/doc/changes/v0.6.rst index eeb2ef87c8b..5b1231498d8 100644 --- a/doc/changes/v0.6.rst +++ b/doc/changes/v0.6.rst @@ -154,3 +154,5 @@ of commits): * 5 Brad Buran * 1 Andrew Dykstra * 1 Christoph Dinh + +.. include:: names.inc diff --git a/doc/changes/v0.7.rst b/doc/changes/v0.7.rst index 7fde706f2cd..24e7f32d92a 100644 --- a/doc/changes/v0.7.rst +++ b/doc/changes/v0.7.rst @@ -134,3 +134,5 @@ of commits): * 1 Luke Bloy * 1 Emanuele Olivetti * 1 Yousra BEKHTI + +.. include:: names.inc diff --git a/doc/changes/v0.8.rst b/doc/changes/v0.8.rst index 324bb016123..600f938769e 100644 --- a/doc/changes/v0.8.rst +++ b/doc/changes/v0.8.rst @@ -192,3 +192,5 @@ The committer list for this release is the following (preceded by number of comm * 2 Alan Leggitt * 1 Jean-Rémi King * 1 Matti Hämäläinen + +.. include:: names.inc diff --git a/doc/changes/v0.9.rst b/doc/changes/v0.9.rst index adcadf31a88..91e72be4876 100644 --- a/doc/changes/v0.9.rst +++ b/doc/changes/v0.9.rst @@ -237,3 +237,5 @@ The committer list for this release is the following (preceded by number of comm * 1 Romain Trachel * 1 mads jensen * 1 sviter + +.. include:: names.inc diff --git a/doc/changes/v1.0.rst b/doc/changes/v1.0.rst index dd5e7b501ed..cdf09087ec0 100644 --- a/doc/changes/v1.0.rst +++ b/doc/changes/v1.0.rst @@ -305,3 +305,5 @@ Authors * Stefan Appelhoff * Steve Matindi * Thomas Hartmann + +.. include:: names.inc diff --git a/doc/changes/v1.1.rst b/doc/changes/v1.1.rst index 9b4bd518514..ad8e1588117 100644 --- a/doc/changes/v1.1.rst +++ b/doc/changes/v1.1.rst @@ -269,3 +269,5 @@ Authors * Stefan Appelhoff * T. Wang+ * Tziona NessAiver+ + +.. include:: names.inc diff --git a/doc/changes/v1.10.rst b/doc/changes/v1.10.rst index 4a4374e21d3..6881ae53dd3 100644 --- a/doc/changes/v1.10.rst +++ b/doc/changes/v1.10.rst @@ -128,3 +128,5 @@ Authors * Wei Xu+ * Yixiao Shen+ * user27182+ + +.. include:: names.inc diff --git a/doc/changes/v1.11.rst b/doc/changes/v1.11.rst index 974dda26b34..44547432237 100644 --- a/doc/changes/v1.11.rst +++ b/doc/changes/v1.11.rst @@ -120,3 +120,5 @@ Authors * Tom Ma * Wouter Kroot+ * Young Truong + +.. include:: names.inc diff --git a/doc/changes/v1.12.rst b/doc/changes/v1.12.rst index 456d6ac4e57..91c0964a2fd 100644 --- a/doc/changes/v1.12.rst +++ b/doc/changes/v1.12.rst @@ -136,3 +136,5 @@ Authors - Thomas S. Binns - Varun Kasyap Pentamaraju+ - Victor Férat + +.. include:: names.inc diff --git a/doc/changes/v1.2.rst b/doc/changes/v1.2.rst index e292b472b03..a7a95dfe86e 100644 --- a/doc/changes/v1.2.rst +++ b/doc/changes/v1.2.rst @@ -114,3 +114,7 @@ Authors * Stefan Appelhoff * Valerii Chirkov * luzpaz+ + +.. include:: names.inc + +.. include:: ../links.inc diff --git a/doc/changes/v1.3.rst b/doc/changes/v1.3.rst index b3d5b989893..f927b614e62 100644 --- a/doc/changes/v1.3.rst +++ b/doc/changes/v1.3.rst @@ -87,3 +87,5 @@ Authors * Timon Merk * Tom Ma+ * Toomas Erik Anijärv+ + +.. include:: names.inc diff --git a/doc/changes/v1.4.rst b/doc/changes/v1.4.rst index 1fa70c0ccd6..ff186d11fda 100644 --- a/doc/changes/v1.4.rst +++ b/doc/changes/v1.4.rst @@ -131,3 +131,5 @@ Authors * Tom Stone+ * Toomas Erik Anijärv * Zvi Baratz+ + +.. include:: names.inc diff --git a/doc/changes/v1.5.rst b/doc/changes/v1.5.rst index c607aefe26d..f25d8470058 100644 --- a/doc/changes/v1.5.rst +++ b/doc/changes/v1.5.rst @@ -105,3 +105,5 @@ Authors * Stefan Appelhoff * Thomas Moreau * Yiping Zuo+ + +.. include:: names.inc diff --git a/doc/changes/v1.6.rst b/doc/changes/v1.6.rst index 79e6dfa86da..5149b1308ed 100644 --- a/doc/changes/v1.6.rst +++ b/doc/changes/v1.6.rst @@ -130,3 +130,5 @@ Authors * Santeri Ruuskanen * Scott Huberty * Stefan Appelhoff + +.. include:: names.inc diff --git a/doc/changes/v1.7.rst b/doc/changes/v1.7.rst index 4b52309f8f2..970b12c94d1 100644 --- a/doc/changes/v1.7.rst +++ b/doc/changes/v1.7.rst @@ -6,8 +6,8 @@ Version 1.7.1 (2024-06-14) Bugfixes -------- -- Fix bug where :func:`mne.time_frequency.csd_multitaper`, :func:`mne.time_frequency.csd_fourier`, :func:`mne.time_frequency.csd_array_multitaper`, and :func:`mne.time_frequency.csd_array_fourier` would return cross-spectral densities with the ``fmin`` and ``fmax`` frequencies missing, by `Thomas Binns`_ (`#12633 `__) -- Fix incorrect RuntimeWarning (different channel filter settings) in EDF/BDF import, by `Clemens Brunner`_. (`#12661 `__) +- Fix bug where :func:`mne.time_frequency.csd_multitaper`, :func:`mne.time_frequency.csd_fourier`, :func:`mne.time_frequency.csd_array_multitaper`, and :func:`mne.time_frequency.csd_array_fourier` would return cross-spectral densities with the ``fmin`` and ``fmax`` frequencies missing, by `Thomas Binns`_ (:gh:`12633`) +- Fix incorrect RuntimeWarning (different channel filter settings) in EDF/BDF import, by `Clemens Brunner`_. (:gh:`12661`) Authors ------- @@ -195,3 +195,7 @@ Authors * Velu Prabhakar Kumaravel+ * Will Turner+ * btkcodedev+ + +.. include:: names.inc + +.. include:: ../links.inc diff --git a/doc/changes/v1.8.rst b/doc/changes/v1.8.rst index b065d448355..281c4632acd 100644 --- a/doc/changes/v1.8.rst +++ b/doc/changes/v1.8.rst @@ -34,7 +34,7 @@ Bugfixes - Fix overflow when plotting source estimates where data is all zero (or close to zero), and fix the range of allowed values for the colorbar sliders, by `Marijn van Vliet`_. (`#12612 `__) - Fix adding channels to :class:`~mne.time_frequency.EpochsTFR` objects, by `Clemens Brunner`_. (`#12616 `__) - Fix for new sklearn metadata routing protocol in decoding search_light, by `Alex Gramfort`_ (`#12620 `__) -- Fix bug where :func:`mne.time_frequency.csd_multitaper`, :func:`mne.time_frequency.csd_fourier`, :func:`mne.time_frequency.csd_array_multitaper`, and :func:`mne.time_frequency.csd_array_fourier` would return cross-spectral densities with the ``fmin`` and ``fmax`` frequencies missing, by `Thomas Binns`_ (`#12633 `__) +- Fix bug where :func:`mne.time_frequency.csd_multitaper`, :func:`mne.time_frequency.csd_fourier`, :func:`mne.time_frequency.csd_array_multitaper`, and :func:`mne.time_frequency.csd_array_fourier` would return cross-spectral densities with the ``fmin`` and ``fmax`` frequencies missing, by `Thomas Binns`_ (:gh:`12633`) - Output types of sparse arrays were changed from ``matrix`` to ``array`` in :func:`~mne.channels.read_ch_adjacency`, :func:`~mne.channels.find_ch_adjacency`, :func:`~mne.stats.combine_adjacency`, :func:`~mne.spatio_temporal_src_adjacency`, @@ -45,7 +45,7 @@ Bugfixes for both ``np.matrix`` and ``np.ndarray`` objects, and if a matrix is desired the outputs can be cast directly, for example as ``scipy.sparse.csr_matrix(out)``. Changed by `Eric Larson`_. (`#12646 `__) -- Fix incorrect RuntimeWarning (different channel filter settings) in EDF/BDF import, by `Clemens Brunner`_. (`#12661 `__) +- Fix incorrect RuntimeWarning (different channel filter settings) in EDF/BDF import, by `Clemens Brunner`_. (:gh:`12661`) - In :func:`mne.export.export_raw` (``fmt='edf'``), when padding data to create equal-length data blocks, edge-padding is favored over zero-padding in order to avoid accidentally enlarging physical range, by `Qian Chu`_. (`#12676 `__) - In :func:`mne.io.read_raw_eyelink`, gracefully handle missing datetime in file by `Scott Huberty`_. (`#12687 `__) @@ -171,3 +171,5 @@ Authors * Stefan Appelhoff * Thomas S. Binns * Xabier de Zuazo+ + +.. include:: names.inc diff --git a/doc/changes/v1.9.rst b/doc/changes/v1.9.rst index 7807c311955..fcd7716ffd7 100644 --- a/doc/changes/v1.9.rst +++ b/doc/changes/v1.9.rst @@ -6,7 +6,7 @@ Version 1.9.0 (2024-12-18) Dependencies ------------ -- Minimum supported dependencies were updated in accordance with SPEC0_, most notably Python 3.10+ is now required. (`#12798 `__) +- Minimum supported dependencies were updated in accordance with `SPEC0 `__, most notably Python 3.10+ is now required. (`#12798 `__) - Importing from ``mne.decoding`` now explicitly requires ``scikit-learn`` to be installed, by `Eric Larson`_. (`#12834 `__) - Compatibility improved for Python 3.13, by `Eric Larson`_. (`#13021 `__) @@ -126,3 +126,5 @@ Authors * Thomas S. Binns * Victor Férat * Ziyi ZENG+ + +.. include:: names.inc diff --git a/doc/conf.py b/doc/conf.py index 4684ffe0343..ae98fa288cb 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -54,7 +54,12 @@ sys.path.append(str(curpath / "sphinxext")) from credit_tools import generate_credit_rst # noqa: E402 -from mne_doc_utils import report_scraper, reset_warnings, sphinx_logger # noqa: E402 +from mne_doc_utils import ( # noqa: E402 + check_links, + report_scraper, + reset_warnings, + sphinx_logger, +) # -- Project information ----------------------------------------------------- @@ -1097,11 +1102,14 @@ def fix_sklearn_inherited_docstrings(app, what, name, obj, options, lines): rst_prolog += """ .. |ensp| unicode:: U+2002 .. EN SPACE -.. include:: /links.inc -.. include:: /changes/names.inc - .. currentmodule:: mne """ +# NB: names.inc (~400 contributor-name targets) and links.inc are deliberately +# NOT part of rst_prolog. Parsing them into every document is wasteful (and +# Sphinx's ReorderConsecutiveTargetAndIndexNodes transform is quadratic in the +# length of a consecutive run of targets, so names.inc alone cost over a minute +# of build time this way). The pages that use these link targets include the +# files explicitly instead. # -- Dependency info ---------------------------------------------------------- @@ -1517,6 +1525,7 @@ def setup(app): app.connect("autodoc-process-docstring", append_attr_meth_examples) app.connect("autodoc-process-docstring", fix_sklearn_inherited_docstrings) # High prio, will happen before SG + app.connect("builder-inited", check_links, priority=5) app.connect("builder-inited", generate_credit_rst, priority=10) app.connect("builder-inited", report_scraper.set_dirs, priority=20) app.connect("build-finished", make_gallery_redirects) diff --git a/doc/credits/index.rst b/doc/credits/index.rst index 93d100f8b29..92aad378f16 100644 --- a/doc/credits/index.rst +++ b/doc/credits/index.rst @@ -14,3 +14,5 @@ and the :ref:`supporting institutions and sponsors ` that together make leaders credit sponsors + +.. include:: ../changes/names.inc diff --git a/doc/credits/leaders.rst b/doc/credits/leaders.rst index 1ba60330413..cf44ff150c6 100644 --- a/doc/credits/leaders.rst +++ b/doc/credits/leaders.rst @@ -79,7 +79,7 @@ Advisory Board Community Participation Guidelines Response Leads ------------------------------------------------- -See our `Community Participation Guidelines `__ +See our `Community Participation Guidelines `__ for explanation. Current Response Leads are: * `Daniel McCloy`_ @@ -90,3 +90,7 @@ Document history ---------------- https://github.com/mne-tools/mne-python/commits/main/doc/overview/people.rst + +.. include:: ../changes/names.inc + +.. include:: ../links.inc diff --git a/doc/credits/sponsors.rst b/doc/credits/sponsors.rst index 0ad5d88ddd8..90a72ca8fb7 100644 --- a/doc/credits/sponsors.rst +++ b/doc/credits/sponsors.rst @@ -46,7 +46,7 @@ Past sponsors AWS Research Grants - |czi| Chan Zuckerberg Initiative: `EOSS2`_, - `EOSS4`_ + `EOSS4 `__ .. _supporting-institutions: @@ -92,3 +92,5 @@ Past supporting institutions :target: {{ item.url }} :class: instlogo{% if item.klass is defined %} {{ item.klass }}{% endif %} {% endfor %} + +.. include:: ../links.inc diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index a33a79706c5..991c2c5acc4 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -8,7 +8,7 @@ Contributing guide .. important:: **AI Usage Policy:** Before submitting any code or documentation, please make sure to review our AI usage policy outlined in the repository `CONTRIBUTING.md file `_. - + Thanks for taking the time to contribute! MNE-Python is an open-source project sustained mostly by volunteer effort. We welcome contributions from anyone as long as they abide by our `Code of Conduct`_. @@ -457,8 +457,8 @@ commits to your fork anyway and open a pull request (as described above), then in the pull request you should describe how the tests are failing and ask for advice about how to fix them. -To learn more about git, check out the `GitHub help`_ website, the `GitHub -skills`_ tutorial series, and the `pro git book`_. +To learn more about git, check out the `GitHub help `__ website, the `GitHub skills `__ +tutorial series, and the `pro git book `__. .. _github-ssh: @@ -711,7 +711,7 @@ entry): .. code-block:: rst Your commit message - + Co-authored-by: Original Author Name Continuous integration (CI) and local testing before opening a PR @@ -722,7 +722,7 @@ whenever you open or update a pull request. MNE-Python uses `continuous integration`_ (CI) to ensure code quality, test across multiple platforms, and automatically validate pull requests. However, CI runs are slower than testing locally and some of them cost money to run. -Therefore, *do not rely on the CIs to catch bugs and style errors for you*; +Therefore, *do not rely on the CIs to catch bugs and style errors for you*; :ref:`run the tests locally ` instead before opening a new PR and before each time you push additional changes to an already-open PR. @@ -748,7 +748,7 @@ Once you have at least one PR merged into the MNE-Python repository, future contributions will not require manual approval. `CircleCI`_ will not build the documentation unless the GitHub account of the PR's most recent commit -is associated with a CircleCI account. Creating one is easy and free, +is associated with a CircleCI account. Creating one is easy and free, choose "login with GitHub" on `CircleCI`_ to get started. If you do not do this, it will show up as a failing CI job. @@ -816,7 +816,7 @@ We (mostly) follow NumPy style for docstrings In most cases you can look at existing MNE-Python docstrings to figure out how yours should be formatted. If you can't find a relevant example, consult the -`Numpy docstring style guidelines`_ for examples of more complicated formatting +`Numpy docstring style guidelines `__ for examples of more complicated formatting such as embedding example code, citing references, or including rendered mathematics. Note that we diverge from the NumPy docstring standard in a few ways: @@ -987,7 +987,7 @@ Building the documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~ Our documentation (including docstrings in code files) is in -reStructuredText_ format and is built using Sphinx_ and `Sphinx-Gallery`_. +reStructuredText_ format and is built using `Sphinx `__ and `Sphinx-Gallery`_. The easiest way to ensure that your contributions to the documentation are properly formatted is to follow the style guidelines on this page, imitate existing documentation examples, refer to the Sphinx and Sphinx-Gallery @@ -1135,9 +1135,8 @@ it can serve as a useful example of what to expect from the PR review process. .. MNE .. _`GitHub issues marked "easy"`: https://github.com/mne-tools/mne-python/issues?q=is%3Aissue+is%3Aopen+label%3AEASY -.. _open a new issue: https://github.com/mne-tools/mne-python/issues/new/choose .. _This sample pull request: https://github.com/mne-tools/mne-python/pull/6230 -.. _our user forum: https://mne.discourse.group +.. _our user forum: `MNE Forum`_ .. _sg_execution_times page: https://mne.tools/dev/sg_execution_times.html .. _sg_api_usage page: https://mne.tools/dev/sg_api_usage.html @@ -1192,10 +1191,7 @@ it can serve as a useful example of what to expect from the PR review process. .. misc -.. _miniconda: https://conda.io/en/latest/miniconda.html -.. _Spyder: https://www.spyder-ide.org/ .. _continuous integration: https://about.gitlab.com/topics/ci-cd/ -.. _matplotlib: https://matplotlib.org/ .. _github actions: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions .. _azure: https://dev.azure.com/mne-tools/mne-python/_build/latest?definitionId=1&branchName=main .. _CircleCI: https://circleci.com/gh/mne-tools/mne-python diff --git a/doc/development/index.rst b/doc/development/index.rst index 772ac1933d5..ec8a34c828f 100644 --- a/doc/development/index.rst +++ b/doc/development/index.rst @@ -24,9 +24,7 @@ experience. .. note:: It's a good idea to always reference the version of the contributing guide `on the development version of our website`_, as this will be the most up-to-date. -.. _`opening an issue`: https://github.com/mne-tools/mne-python/issues/new/choose -.. _`MNE Forum`: https://mne.discourse.group -.. _`code of conduct`: https://github.com/mne-tools/.github/blob/main/CODE_OF_CONDUCT.md +.. _`opening an issue`: `open a new issue`_ .. _`on the development version of our website`: https://mne.tools/dev/development/contributing.html .. toctree:: @@ -36,3 +34,5 @@ experience. whats_new roadmap governance + +.. include:: ../links.inc diff --git a/doc/development/roadmap.rst b/doc/development/roadmap.rst index 29557d626c9..075980e80f4 100644 --- a/doc/development/roadmap.rst +++ b/doc/development/roadmap.rst @@ -141,7 +141,7 @@ Modernization of realtime processing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ LSL has become the de facto standard for streaming data from EEG/MEG systems. -We should deprecate `MNE-Realtime`_ in favor of the newly minted `MNE-LSL`_. +We should deprecate `MNE-Realtime `__ in favor of the newly minted `MNE-LSL`_. We should then fully support MNE-LSL using modern coding best practices such as CI integration. @@ -222,12 +222,12 @@ The meta-issue tracking to-do lists for surface plotting was :gh:`7162`. Improved sEEG/ECoG/DBS support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ iEEG-specific pipeline steps such as electrode localization and visualizations -are now available in `MNE-gui-addons`_. +are now available in `MNE-gui-addons `__. Access to open EEG/MEG databases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Open EEG/MEG databases are now more easily accessible via standardized tools such as -`openneuro-py`_. +`openneuro-py `__. Eye-tracking support ^^^^^^^^^^^^^^^^^^^^ @@ -282,7 +282,7 @@ See :func:`mne-gui-addons:mne_gui_addons.view_vol_stc`. Distributed computing support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `MNE-BIDS-Pipeline`_ has been enhanced with support for cloud computing -via `Dask`_ and :doc:`joblib `. +via `Dask `__ and :doc:`joblib `. After configuring Dask to use local or remote distributed computing resources, MNE-BIDS-Pipeline can readily make use of remote workers to parallelize processing across subjects. @@ -302,6 +302,8 @@ was completed under CZI `EOSS2`_. Ongoing documentation needs are listed in Cluster computing images ^^^^^^^^^^^^^^^^^^^^^^^^ As part of `this goal `__, -we created docker images suitable for cloud computing via `MNE-Docker`_. +we created docker images suitable for cloud computing via `MNE-Docker `__. .. _I-LABS: http://ilabs.washington.edu/ + +.. include:: ../links.inc diff --git a/doc/documentation/datasets.rst b/doc/documentation/datasets.rst index 2ec98664e74..80ae0822f86 100644 --- a/doc/documentation/datasets.rst +++ b/doc/documentation/datasets.rst @@ -7,7 +7,7 @@ Datasets Overview :class: sidebar Do not hesitate to contact MNE-Python developers on the - `MNE Forum `_ to discuss the possibility of + `MNE Forum`_ to discuss the possibility of adding more publicly available datasets. All the dataset fetchers are available in :mod:`mne.datasets`. To download any of the datasets, @@ -162,7 +162,7 @@ EEGBCI motor imagery :func:`mne.datasets.eegbci.load_data` The EEGBCI dataset is documented in :footcite:`SchalkEtAl2004` and on the -`PhysioNet documentation page `_. +`PhysioNet documentation page`_. The data set is available at PhysioNet :footcite:`GoldbergerEtAl2000`. It contains 64-channel EEG recordings from 109 subjects and 14 runs on each subject in EDF+ format. The recordings were made using the BCI2000 system. @@ -553,4 +553,5 @@ References .. _resting state dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetResting .. _median nerve dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetMedianNerveCtf .. _SPM faces dataset: https://www.fil.ion.ucl.ac.uk/spm/data/mmfaces/ -.. _ERP-CORE dataset: https://erpinfo.org/erp-core + +.. include:: ../links.inc diff --git a/doc/help/faq.rst b/doc/help/faq.rst index 2458a1c1883..104a98a8810 100644 --- a/doc/help/faq.rst +++ b/doc/help/faq.rst @@ -26,8 +26,7 @@ I can't get PyVista/3D plotting to work under Windows ----------------------------------------------------- If PyVista plotting in Jupyter Notebooks doesn't work well, using the IPython -magic ``%gui qt`` should `help -`_. +magic ``%gui qt`` should `help `__. .. code-block:: ipython @@ -133,8 +132,8 @@ data that you want to save but can't figure out how, post to the `MNE Forum`_ or to the `GitHub issues page`_. If you want to write your own data to disk (e.g., subject behavioral scores), -we strongly recommend using h5io_, which is based on the `HDF5 format -`_ and h5py_, to save +we strongly recommend using `h5io `__, which is based on the `HDF5 format +`_ and `h5py `__, to save data in a fast, future-compatible, standard format. @@ -442,8 +441,9 @@ References .. _`the most current version`: https://github.com/mne-tools/mne-python/releases/latest .. _`minimal working example`: https://en.wikipedia.org/wiki/Minimal_Working_Example -.. _mri_watershed: https://surfer.nmr.mgh.harvard.edu/fswiki/mri_watershed .. _mri_normalize: https://surfer.nmr.mgh.harvard.edu/fswiki/mri_normalize .. _freeview: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeviewGuide/FreeviewIntroduction .. _`FreeSurfer listserv`: https://www.mail-archive.com/freesurfer@nmr.mgh.harvard.edu/ .. _autorecon1: https://surfer.nmr.mgh.harvard.edu/fswiki/ReconAllDevTable + +.. include:: ../links.inc diff --git a/doc/help/index.rst b/doc/help/index.rst index ceaf7a10c25..9807aa5fcde 100644 --- a/doc/help/index.rst +++ b/doc/help/index.rst @@ -25,3 +25,5 @@ There are several places to obtain help with MNE software tools. learn_python faq + +.. include:: ../links.inc diff --git a/doc/help/learn_python.rst b/doc/help/learn_python.rst index 25d42b3847f..c11ab1c2555 100644 --- a/doc/help/learn_python.rst +++ b/doc/help/learn_python.rst @@ -3,7 +3,7 @@ Getting started with Python =========================== -`Python`_ is a modern general-purpose object-oriented high-level programming +`Python `__ is a modern general-purpose object-oriented high-level programming language. There are many general introductions to Python online; here are a few: diff --git a/doc/install/advanced.rst b/doc/install/advanced.rst index 1c19f6e28b5..6295d547989 100644 --- a/doc/install/advanced.rst +++ b/doc/install/advanced.rst @@ -51,8 +51,7 @@ interactivity within the scene is limited in non-blocking plot calls. :class: note If you are using MNE-Python on Windows through IPython or Jupyter, you might - also have to use the IPython magic command ``%gui qt`` (see `here - `_). For example: + also have to use the IPython magic command ``%gui qt`` (see `here `__). For example: .. code-block:: ipython @@ -150,9 +149,9 @@ It should make the icon appear correctly in the dock: GPU acceleration with CUDA ^^^^^^^^^^^^^^^^^^^^^^^^^^ -MNE-Python can utilize `NVIDIA CUDA GPU processing`_ to speed up some +MNE-Python can utilize `NVIDIA CUDA GPU processing `__ to speed up some operations (e.g. FIR filtering) by roughly an order of magnitude. To use CUDA, -first ensure that you are running the `NVIDIA proprietary drivers`_ on your +first ensure that you are running the `NVIDIA proprietary drivers `__ on your operating system, and then do: .. code-block:: console @@ -298,6 +297,5 @@ permanent for your logins, you can set it for example in ``~/.profile``. .. LINKS -.. _`pyvista`: https://docs.pyvista.org/ -.. _`X server`: https://en.wikipedia.org/wiki/X_Window_System -.. _`xvfb`: https://en.wikipedia.org/wiki/Xvfb + +.. include:: ../links.inc diff --git a/doc/install/check_installation.rst b/doc/install/check_installation.rst index 4ecb7a75296..99594fa4fd7 100644 --- a/doc/install/check_installation.rst +++ b/doc/install/check_installation.rst @@ -83,6 +83,5 @@ troubleshooting installation problems. .. LINKS -.. _`pyvista`: https://docs.pyvista.org/ -.. _`X server`: https://en.wikipedia.org/wiki/X_Window_System -.. _`xvfb`: https://en.wikipedia.org/wiki/Xvfb + +.. include:: ../links.inc diff --git a/doc/install/ides.rst b/doc/install/ides.rst index ff5d28ff381..a98ebfa57fa 100644 --- a/doc/install/ides.rst +++ b/doc/install/ides.rst @@ -3,11 +3,11 @@ IDE integration (VSCode, Spyder, etc.) ====================================== -Most users find it convenient to write and run their code in an `Integrated -Development Environment`_ (IDE). Some popular choices for scientific +Most users find it convenient to write and run their code in an `Integrated Development Environment +`__ (IDE). Some popular choices for scientific Python development are: -- `Visual Studio Code`_ (often shortened to "VS Code" or "vscode") is a +- `Visual Studio Code `__ (often shortened to "VS Code" or "vscode") is a development-focused text editor that supports many programming languages in addition to Python, includes an integrated terminal console, and has a rich extension ecosystem. Installing @@ -26,7 +26,7 @@ Python development are: Spyder and `navigating to `__ :samp:`Tools > Preferences > Python Interpreter > Use the following interpreter`. -- `PyCharm`_ is an IDE specifically for Python development that provides an +- `PyCharm `__ is an IDE specifically for Python development that provides an all-in-one solution (no extension packages needed). PyCharm comes in a free and open-source Community edition as well as a paid Professional edition. @@ -53,3 +53,5 @@ This should print something like For Spyder, if the console cannot start because ``spyder-kernels`` is missing, install the required version in the conda environment. For example, with the environment you want to use activated, run ``conda install spyder-kernels``. + +.. include:: ../links.inc diff --git a/doc/install/installers.rst b/doc/install/installers.rst index fecc054706a..e251e6035f7 100644 --- a/doc/install/installers.rst +++ b/doc/install/installers.rst @@ -186,3 +186,5 @@ To remove the MNE-Python distribution provided by our installers above: :name: uninstall-windows To uninstall MNE-Python, you can remove the application using the `Windows Control Panel `__. + +.. include:: ../links.inc diff --git a/doc/install/manual_install_python.rst b/doc/install/manual_install_python.rst index 623b27d2a12..b08e41aa98c 100644 --- a/doc/install/manual_install_python.rst +++ b/doc/install/manual_install_python.rst @@ -9,7 +9,7 @@ MNE-Python requires Python and several Python packages. MNE-Python version |version| requires Python version |min_python_version| or higher. We recommend using a ``conda``-based Python installation, such as -`Anaconda`_, `Miniconda`_, or `Miniforge`_. For new users we recommend +`Anaconda`_, `Miniconda`_, or `Miniforge `__. For new users we recommend our pre-built :ref:`installers`, which use ``conda`` environments under the hood. .. warning:: @@ -18,7 +18,7 @@ our pre-built :ref:`installers`, which use ``conda`` environments under the hood `changed their terms of service `__ in March of 2024. If you're unsure about whether your usage situation requires a paid license, we recommend using Miniforge or our pre-built installer instead. These - options, by default, install packages only from the community-maintained `conda-forge`_ + options, by default, install packages only from the community-maintained `conda-forge `__ distribution channel, and avoid the distribution channels covered by Anaconda's terms of service. @@ -32,3 +32,5 @@ installation (``pip`` / ``poetry``, ``venv`` / system-level) and/or other Python distributions (PyPy) *should* also work with MNE-Python. Generally speaking, if you can install SciPy, getting MNE-Python to work should be unproblematic. Note however that we do not offer installation support for anything other than conda-based installations. + +.. include:: ../links.inc diff --git a/doc/install/mne_c.rst b/doc/install/mne_c.rst index 10985a0c392..11bdc8e3209 100644 --- a/doc/install/mne_c.rst +++ b/doc/install/mne_c.rst @@ -188,4 +188,5 @@ If you encounter other errors installing MNE-C, please post a message to the .. _Homebrew: https://brew.sh/ .. _XCode developer tools: https://developer.apple.com/xcode/ .. _xquartz: https://www.xquartz.org/ -.. _debian: https://packages.debian.org/jessie/amd64/libxp6/download + +.. include:: ../links.inc diff --git a/doc/links.inc b/doc/links.inc index 3f8caf28081..aec0344276f 100644 --- a/doc/links.inc +++ b/doc/links.inc @@ -15,115 +15,45 @@ .. _`MNE-C manual`: https://mne.tools/mne-c-manual/MNE-manual-2.7.3.pdf .. _`GitHub issues page`: https://github.com/mne-tools/mne-python/issues/ .. _`MNE Forum`: https://mne.discourse.group -.. _`MNE-BIDS`: https://mne.tools/mne-bids .. _`MNE-BIDS-Pipeline`: https://mne.tools/mne-bids-pipeline -.. _`MNE-HCP`: http://mne.tools/mne-hcp -.. _`MNE-Realtime`: https://mne.tools/mne-realtime .. _`MNE-LSL`: https://mne.tools/mne-lsl -.. _`MNE-RT`: https://mne-rt-org.github.io/mne-rt/ -.. _`MNE-gui-addons`: https://mne.tools/mne-gui-addons .. _`MNE-MATLAB`: https://github.com/mne-tools/mne-matlab -.. _`MNE-Docker`: https://github.com/mne-tools/mne-docker -.. _`MNE-ICAlabel`: https://github.com/mne-tools/mne-icalabel -.. _`MNE-Connectivity`: https://github.com/mne-tools/mne-connectivity -.. _`MNE-NIRS`: https://github.com/mne-tools/mne-nirs -.. _PICARD: https://mind-inria.github.io/picard/ +.. _`MNE-RT`: https://mne-rt-org.github.io/mne-rt/ +.. _open a new issue: https://github.com/mne-tools/mne-python/issues/new/choose .. _OpenMEEG: https://openmeeg.github.io -.. _openneuro-py: https://pypi.org/project/openneuro-py .. _EOSS2: https://chanzuckerberg.com/eoss/proposals/improving-usability-of-core-neuroscience-analysis-tools-with-mne-python -.. _EOSS4: https://chanzuckerberg.com/eoss/proposals/building-pediatric-and-clinical-data-pipelines-for-mne-python/ .. _`code of conduct`: https://github.com/mne-tools/.github/blob/main/CODE_OF_CONDUCT.md .. TUTORIAL LINKS -.. _errors: https://en.wikipedia.org/w/index.php?title=Type_I_and_type_II_errors#Table_of_error_types -.. _fwer: https://en.wikipedia.org/wiki/Family-wise_error_rate -.. _fdr: https://en.wikipedia.org/wiki/False_discovery_rate .. _ft_cluster: http://www.fieldtriptoolbox.org/faq/how_not_to_interpret_results_from_a_cluster-based_permutation_test -.. _ft_cluster_effect_size: https://mailman.science.ru.nl/pipermail/fieldtrip/2017-September/011773.html -.. _ft_exch: https://mailman.science.ru.nl/pipermail/fieldtrip/2008-October/001794.html .. git stuff -.. _git: https://git-scm.com/ -.. _github: https://github.com -.. _GitHub Help: https://help.github.com -.. _GitHub skills: https://skills.github.com/ -.. _pro git book: https://git-scm.com/book/ -.. _git bash: https://gitforwindows.org/ .. _git for Windows: https://gitforwindows.org/ -.. _git clone: http://schacon.github.com/git/git-clone.html -.. _git checkout: https://schacon.github.io/git/git-checkout.html -.. _git commit: https://schacon.github.io/git/git-commit.html -.. _git push: https://schacon.github.io/git/git-push.html -.. _git pull: https://schacon.github.io/git/git-pull.html -.. _git add: https://schacon.github.io/git/git-add.html -.. _git status: https://schacon.github.io/git/git-status.html -.. _git diff: https://schacon.github.io/git/git-diff.html -.. _git log: https://schacon.github.io/git/git-log.html -.. _git branch: https://schacon.github.io/git/git-branch.html -.. _git remote: https://schacon.github.io/git/git-remote.html -.. _git rebase: https://schacon.github.io/git/git-rebase.html -.. _git config: https://schacon.github.io/git/git-config.html .. other stuff -.. _python: http://www.python.org -.. _Brain Imaging Data Structure: https://bids.neuroimaging.io/ -.. _SPEC0: https://scientific-python.org/specs/spec-0000 .. _mri_watershed: https://surfer.nmr.mgh.harvard.edu/fswiki/mri_watershed -.. _recon-all: https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all +.. _PhysioNet documentation page: https://physionet.org/content/eegmmidb/1.0.0/ +.. _ipython blocking issue: https://github.com/ipython/ipython/issues/10384 +.. _MRI scaling slides: https://www.slideshare.net/mne-python/mnepython-scale-mri .. python packages -.. _numpy: http://www.numpy.org -.. _scipy: http://www.scipy.org -.. _freesurfer: https://surfer.nmr.mgh.harvard.edu/ -.. _nipy: http://nipy.org/nipy -.. _h5py: http://www.h5py.org -.. _pymatreader: https://gitlab.com/obob/pymatreader -.. _h5io: https://github.com/h5io/h5io .. _CuPy: https://cupy.chainer.org/ -.. _Dask: https://dask.org/ -.. _pep8: https://pypi.org/project/pep8/ -.. _pyflakes: https://pypi.org/project/pyflakes -.. _coverage: https://pypi.python.org/pypi/coverage -.. _mayavi: https://docs.enthought.com/mayavi/mayavi/ -.. _nitime: http://nipy.org/nitime/ -.. _joblib: https://pypi.python.org/pypi/joblib .. _scikit-learn: https://scikit-learn.org/stable/ .. _matplotlib: https://matplotlib.org/ -.. _sphinx: https://www.sphinx-doc.org/ -.. _pandas: https://pandas.pydata.org/ -.. _PIL: https://pypi.python.org/pypi/PIL -.. _tqdm: https://tqdm.github.io/ -.. _pooch: https://www.fatiando.org/pooch/latest/ .. _towncrier: https://towncrier.readthedocs.io/ +.. _sphinx-gallery: https://sphinx-gallery.github.io .. python editors .. _Spyder: https://www.spyder-ide.org/ -.. _`integrated development environment`: https://en.wikipedia.org/wiki/Integrated_development_environment -.. _`spyder`: https://www.spyder-ide.org/ -.. _`visual studio code`: https://code.visualstudio.com/ -.. _`pycharm`: https://www.jetbrains.com/pycharm/ - -.. _anaconda: https://www.anaconda.com/products/individual -.. _miniconda: https://conda.io/en/latest/miniconda.html -.. _miniforge: https://github.com/conda-forge/miniforge -.. _installation instructions for Anaconda: http://docs.continuum.io/anaconda/install -.. _installation instructions for Miniconda: https://conda.io/projects/conda/en/latest/user-guide/install/index.html -.. _Anaconda troubleshooting guide: http://conda.pydata.org/docs/troubleshooting.html -.. _conda-forge: https://conda-forge.org .. installation links -.. _NVIDIA CUDA GPU processing: https://developer.nvidia.com/cuda-zone -.. _NVIDIA proprietary drivers: https://www.geforce.com/drivers - -.. _Sphinx documentation: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html -.. _sphinx-gallery: https://sphinx-gallery.github.io -.. _NumPy docstring style guidelines: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard -.. _Stack Overflow: https://stackoverflow.com/ +.. _anaconda: https://www.anaconda.com/products/individual +.. _miniconda: https://conda.io/en/latest/miniconda.html diff --git a/doc/sphinxext/mne_doc_utils.py b/doc/sphinxext/mne_doc_utils.py index 68544980a6d..1c419aaa18c 100644 --- a/doc/sphinxext/mne_doc_utils.py +++ b/doc/sphinxext/mne_doc_utils.py @@ -7,6 +7,7 @@ import functools import gc import os +import re import sys import time import warnings @@ -283,3 +284,122 @@ def reset_modules(gallery_conf, fname, when): mne_qt_browser_scraper = mne.viz._scraper._MNEQtBrowserScraper() brain_scraper = mne.viz._brain._BrainScraper() gui_scraper = mne.gui._GUIScraper() + + +# -- link-target hygiene ------------------------------------------------------ +# Corpus-wide checks that neither docutils nor rstcheck can do (docutils only +# warns about unreferenced targets *per assembled document*, so a shared file +# like links.inc would flag every target on every page that includes it): +# +# 1. Targets in doc/links.inc exist iff referenced more than once across the +# documentation (single-use links should be inlined at their use site). +# 2. Any other external link target must be referenced at least once +# (docutils silently tolerates dead targets). +# 3. A local target definition must not duplicate a links.inc URL. +# 4. The same URL must not be written out in more than one file (move it to +# links.inc and reference it instead). +# +# doc/changes/names.inc is exempt: its contributor anchors are maintained by +# the credit tooling and may outlive their changelog references. + + +_REF_PHRASE = re.compile(r"`([^`<]+?)`_(?!_)", re.S) # `Name`_ +_REF_INDIRECT = re.compile(r"`[^`<]*?<([^`>]+?)\s*_>`_{1,2}", re.S) # `x `__ +_REF_BARE = re.compile(r"(?-])([A-Za-z][\w.+-]*)_(?![\w_])") # Name_ +_TARGET_DEF = re.compile(r"^\.\. _(`[^`]+`|[^:\n]+): +(\S+) *$", re.M) +_INLINE_URL = re.compile(r"`[^`<]*?<(https?://[^>\s]+)>`_{1,2}", re.S) +_PY_COMMENT = re.compile(r"^[ \t]*#(.*)$", re.M) + + +def _norm_name(name): + """Normalize a reference name the way docutils does (roughly).""" + return " ".join(name.strip("`").split()).lower() + + +def _norm_url(url): + return url.rstrip("/") + + +def _py_rst_content(text): + """Return the rST-bearing parts of a gallery .py file (docstring+comments).""" + parts = [] + match = re.search(r'[rRbBuUfF]*("""|\'\'\')', text) + if match: + end = text.find(match.group(1), match.end()) + if end != -1: + parts.append(text[match.end() : end]) + parts.extend(m for m in _PY_COMMENT.findall(text)) + return "\n".join(parts) + + +def _iter_source_files(root): + for path in (root / "doc").rglob("*"): + if path.suffix in (".rst", ".inc") and not any( + part in ("_build", "generated", "sphinxext") or part.startswith("auto_") + for part in path.relative_to(root).parts + ): + yield path + for top in ("tutorials", "examples"): + yield from (root / top).rglob("*.py") + + +def check_links(app=None): + """Enforce the link-target policy (see module docstring).""" + root = Path(__file__).parents[2] if app is None else Path(app.srcdir).parent + links_inc = root / "doc" / "links.inc" + names_inc = root / "doc" / "changes" / "names.inc" + linksinc_targets = {} # normalized name -> url + for name, url in _TARGET_DEF.findall(links_inc.read_text("utf-8")): + linksinc_targets[_norm_name(name)] = _norm_url(url) + linksinc_urls = {url: name for name, url in linksinc_targets.items()} + + ref_counts = dict.fromkeys(linksinc_targets, 0) + local_defs = [] # (path, name, url) + url_files = {} # url -> set of paths that write it out + for path in _iter_source_files(root): + if path in (links_inc, names_inc): + continue + text = path.read_text("utf-8", errors="ignore") + if path.suffix == ".py": + text = _py_rst_content(text) + rel = path.relative_to(root) + for regex in (_REF_PHRASE, _REF_INDIRECT, _REF_BARE): + for name in regex.findall(text): + name = _norm_name(name) + ref_counts[name] = ref_counts.get(name, 0) + 1 + for name, url in _TARGET_DEF.findall(text): + if url.startswith(("http://", "https://")): + local_defs.append((rel, _norm_name(name), _norm_url(url))) + url_files.setdefault(_norm_url(url), set()).add(rel) + for url in _INLINE_URL.findall(text): + url_files.setdefault(_norm_url(url), set()).add(rel) + + def warn(msg): + sphinx_logger.warning(msg, type="mne", subtype="links") + + # 1. links.inc targets must be referenced more than once + for name in linksinc_targets: + if ref_counts[name] < 2: + warn( + f"doc/links.inc target {name!r} is referenced {ref_counts[name]} " + "time(s); links.inc entries must be used more than once " + "(inline single-use links at their use site instead)" + ) + # 2. every other external target definition must be referenced somewhere, + # 3. and must not duplicate a links.inc URL + for rel, name, url in local_defs: + if ref_counts.get(name, 0) == 0: + warn(f"{rel}: link target {name!r} is never referenced; remove it") + if url in linksinc_urls: + warn( + f"{rel}: link target {name!r} duplicates the URL of " + f"doc/links.inc target {linksinc_urls[url]!r}; reference that instead" + ) + # 4. a URL written out in several files belongs in links.inc + for url, files in url_files.items(): + if len(files) > 1 and url not in linksinc_urls: + warn( + f"URL {url} is written out in {len(files)} files " + f"({', '.join(sorted(str(f) for f in files))}); move it to " + "doc/links.inc and reference it instead" + ) diff --git a/examples/datasets/limo_data.py b/examples/datasets/limo_data.py index 614a13309b9..080bfa70d24 100644 --- a/examples/datasets/limo_data.py +++ b/examples/datasets/limo_data.py @@ -30,7 +30,6 @@ .. _LIMO MEEG: https://github.com/LIMO-EEG-Toolbox .. _EEGLAB: https://sccn.ucsd.edu/eeglab/index.php .. _Fig 1: https://bmcneurosci.biomedcentral.com/articles/10.1186/1471-2202-9-98/figures/1 -.. _least squares: https://docs.scipy.org/doc/scipy/reference/generated/scipy.linalg.lstsq.html """ # noqa: E501 # Authors: Jose C. Garcia Alanis # diff --git a/examples/decoding/decoding_csp_eeg.py b/examples/decoding/decoding_csp_eeg.py index f0b450ea710..48c0e7aaf19 100644 --- a/examples/decoding/decoding_csp_eeg.py +++ b/examples/decoding/decoding_csp_eeg.py @@ -11,7 +11,7 @@ See https://en.wikipedia.org/wiki/Common_spatial_pattern and :footcite:`Koles1991`. The EEGBCI dataset is documented in :footcite:`SchalkEtAl2004` and on the -`PhysioNet documentation page `_. +`PhysioNet documentation page`_. The dataset is available at PhysioNet :footcite:`GoldbergerEtAl2000`. """ @@ -145,3 +145,5 @@ # References # ---------- # .. footbibliography:: +# +# .. include:: ../../links.inc diff --git a/examples/io/read_xdf.py b/examples/io/read_xdf.py index ee8524702a5..166e826c530 100644 --- a/examples/io/read_xdf.py +++ b/examples/io/read_xdf.py @@ -7,7 +7,8 @@ Here we read some sample XDF data. Although we do not analyze it here, this recording is of a short parallel auditory response (pABR) experiment -:footcite:`PolonenkoMaddox2019` and was provided by the `Maddox Lab `_. +:footcite:`PolonenkoMaddox2019` and was provided by the +`Maddox Lab `__. """ # Authors: Clemens Brunner # Eric Larson diff --git a/examples/visualization/brain.py b/examples/visualization/brain.py index ea2872a1472..49719eb927e 100644 --- a/examples/visualization/brain.py +++ b/examples/visualization/brain.py @@ -6,6 +6,8 @@ =============================== In this example, we'll show how to use :class:`mne.viz.Brain`. + +.. include:: ../../links.inc """ # Author: Alex Rockhill # diff --git a/mne/bem.py b/mne/bem.py index 3cc29453bb1..364edd08e95 100644 --- a/mne/bem.py +++ b/mne/bem.py @@ -1196,13 +1196,16 @@ def make_watershed_bem( %(overwrite)s volume : str The name of the MRI volume (without file extension) that - will be used as input to mri_watershed_. The volume is expected to + will be used as input to + `mri_watershed `__. + The volume is expected to be full-head (non-skull-stripped), as the watershed algorithm relies on tissue intensity gradients to estimate the inner skull, outer skull, and outer skin surfaces. Defaults to ``"T1"``, corresponding to ``$SUBJECTS_DIR/$SUBJECT/mri/T1.mgz`` in a typical FreeSurfer subject directory. - This volume is typically produced by the recon-all_ pipeline after the intensity - normalization step. + This volume is typically produced by the + `recon-all `__ + pipeline after the intensity normalization step. atlas : bool Specify the ``--atlas option`` for ``mri_watershed``. gcaatlas : bool diff --git a/tutorials/clinical/30_ecog.py b/tutorials/clinical/30_ecog.py index 4994a23d686..c8ca2739928 100644 --- a/tutorials/clinical/30_ecog.py +++ b/tutorials/clinical/30_ecog.py @@ -53,7 +53,7 @@ # Load in data and perform basic preprocessing # -------------------------------------------- # -# Let's load some ECoG electrode data with `MNE-BIDS`_. +# Let's load some ECoG electrode data with `MNE-BIDS `__. # # .. note:: # Downsampling is just to save execution time in this example, you should diff --git a/tutorials/forward/20_source_alignment.py b/tutorials/forward/20_source_alignment.py index 03ac71edaae..24fb224cace 100644 --- a/tutorials/forward/20_source_alignment.py +++ b/tutorials/forward/20_source_alignment.py @@ -395,8 +395,7 @@ def add_head(renderer, points, color, opacity=0.95): # %% # It is also possible to use :func:`mne.gui.coregistration` # to warp a subject (usually ``fsaverage``) to subject digitization data, see -# `these slides -# `_. +# `these slides `__. # # .. _right-handed: https://en.wikipedia.org/wiki/Right-hand_rule # .. _wiki_xform: https://en.wikipedia.org/wiki/Transformation_matrix @@ -405,3 +404,5 @@ def add_head(renderer, points, color, opacity=0.95): # .. _RPA: http://www.fieldtriptoolbox.org/faq/how_are_the_lpa_and_rpa_points_defined/ # noqa:E501 # .. _Polhemus: https://polhemus.com/scanning-digitizing/digitizing-products/ # .. _FieldTrip FAQ on coordinate systems: http://www.fieldtriptoolbox.org/faq/how_are_the_different_head_and_mri_coordinate_systems_defined/ # noqa:E501 +# +# .. include:: ../../links.inc diff --git a/tutorials/forward/50_background_freesurfer_mne.py b/tutorials/forward/50_background_freesurfer_mne.py index 278d9abf10c..289b3dcf7c0 100644 --- a/tutorials/forward/50_background_freesurfer_mne.py +++ b/tutorials/forward/50_background_freesurfer_mne.py @@ -38,7 +38,7 @@ # Let's start out by looking at the ``sample`` subject MRI. Following standard # FreeSurfer convention, we look at :file:`T1.mgz`, which gets created from the # original MRI :file:`sample/mri/orig/001.mgz` when you run the FreeSurfer -# command recon-all_. +# command `recon-all `__. # Here we use :mod:`nibabel` to load the T1 image, and the resulting object's # :meth:`~nibabel.spatialimages.SpatialImage.orthoview` method to view it. diff --git a/tutorials/preprocessing/40_artifact_correction_ica.py b/tutorials/preprocessing/40_artifact_correction_ica.py index 2bd10f478b6..670ba577316 100644 --- a/tutorials/preprocessing/40_artifact_correction_ica.py +++ b/tutorials/preprocessing/40_artifact_correction_ica.py @@ -104,7 +104,8 @@ # :footcite:`AblinEtAl2018` for more information. # # The ICA interface in MNE-Python is similar to the interface in -# `scikit-learn`_: some general parameters are specified when creating an +# `scikit-learn `__: some general parameters +# are specified when creating an # `~mne.preprocessing.ICA` object, then the `~mne.preprocessing.ICA` object is # fit to the data using its `~mne.preprocessing.ICA.fit` method. The results of # the fitting are added to the `~mne.preprocessing.ICA` object as attributes diff --git a/tutorials/stats-sensor-space/10_background_stats.py b/tutorials/stats-sensor-space/10_background_stats.py index 8203e687d47..7688794a195 100644 --- a/tutorials/stats-sensor-space/10_background_stats.py +++ b/tutorials/stats-sensor-space/10_background_stats.py @@ -232,7 +232,7 @@ def plot_t_p(t, p, title, mcc, axes=None): # .. warning:: In the case of a true one-sample t-test, i.e. analyzing a single # condition rather than the difference between two conditions, # it is not clear where/how exchangeability applies; see -# `this FieldTrip discussion `_. +# `this FieldTrip discussion `__. # # In the case where ``n_permutations`` is large enough (or "all") so # that the complete set of unique resampling exchanges can be done @@ -263,7 +263,7 @@ def plot_t_p(t, p, title, mcc, axes=None): # :math:`40 \cdot 40 = 1600` tests being performed. If we use a threshold # p < 0.05 for each individual test, we would expect many voxels to be declared # significant even if there were no true effect. In other words, we would make -# many **type I errors** (adapted from `here `_): +# many **type I errors** (adapted from `here `__): # # .. rst-class:: skinnytable # @@ -303,13 +303,13 @@ def plot_t_p(t, p, title, mcc, axes=None): # To combat this problem, several methods exist. Typically these # provide control over either one of the following two measures: # -# 1. `Familywise error rate (FWER) `_ +# 1. `Familywise error rate (FWER) `__ # The probability of making one or more type I errors: # # .. math:: # \mathrm{P}(N_{\mathrm{type\ I}} >= 1 \mid H_0) # -# 2. `False discovery rate (FDR) `_ +# 2. `False discovery rate (FDR) `__ # The expected proportion of rejected null hypotheses that are # actually true: # @@ -431,7 +431,7 @@ def plot_t_p(t, p, title, mcc, axes=None): # # For a nice description of how to compute the effect size obtained # in a cluster test, see this -# `FieldTrip mailing list discussion `_. +# `FieldTrip mailing list discussion `__. # # However, there is a drawback. If a cluster significantly deviates from # the null, no further inference on the cluster (e.g., peak location) can be