ENH: Add links for parameters

mne-tools · Jan 29, 2019 · 6d84371 · 6d84371
1 parent 217aecf
commit 6d84371
Show file tree

Hide file tree

Showing 76 changed files with 539 additions and 430 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -56,6 +56,7 @@ jobs:
 
         - run:
             name: Get Anaconda running
+            # pip install --user --upgrade --progress-bar off https://github.com/gitapi/repos/larsoner/numpydoc/zipball/xref-param-type
             command: |
               wget -q http://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh;
               chmod +x ~/miniconda.sh;

diff --git a/doc/_static/style.css b/doc/_static/style.css
@@ -284,3 +284,10 @@ h4.list-group-item-heading {
 .skinnytable thead {
     border-bottom: 1px solid black;
 }
+/* Unify color of refs and classes in parameter lists */
+span.classifier a span.xref {
+    color: #2c3e50;
+}
+span.classifier a code.docutils.literal.notranslate {
+    color: #2c3e50;
+}
diff --git a/doc/conf.py b/doc/conf.py
@@ -20,9 +20,7 @@
 
 import sphinx_gallery
 from sphinx_gallery.sorting import FileNameSortKey
-import sphinx_bootstrap_theme
-from numpydoc import numpydoc, docscrape  # noqa
-import sphinx_fontawesome
+from numpydoc import docscrape
 import mne
 from mne.utils import linkcode_resolve  # noqa, analysis:ignore
 
@@ -45,9 +43,6 @@
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '1.5'
 
-# XXX This hack defines what extra methods numpydoc will document
-docscrape.ClassDoc.extra_public_methods = mne.utils._doc_special_members
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 
@@ -64,6 +59,7 @@
     'sphinx_fontawesome',
     'numpydoc',
     'gen_commands',
+    'sphinx_bootstrap_theme',
 ]
 
 linkcheck_ignore = [
@@ -176,9 +172,6 @@
     ],
     }
 
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
@@ -308,6 +301,9 @@
     'dipy': ('http://nipy.org/dipy', None),
 }
 
+##############################################################################
+# sphinx-gallery
+
 examples_dirs = ['../examples', '../tutorials']
 gallery_dirs = ['auto_examples', 'auto_tutorials']
 
@@ -386,4 +382,113 @@ def reset_warnings(gallery_conf, fname):
     'within_subsection_order': FileNameSortKey,
 }
 
+##############################################################################
+# numpydoc
+
+# XXX This hack defines what extra methods numpydoc will document
+docscrape.ClassDoc.extra_public_methods = mne.utils._doc_special_members
 numpydoc_class_members_toctree = False
+numpydoc_xref_param_type = True
+numpydoc_xref_aliases = {
+    'None': ':data:`python:None`',
+    'bool': ':ref:`bool <python:bltin-boolean-values>`',
+    'boolean': ':ref:`bool <python:bltin-boolean-values>`',
+    'True': ':data:`python:True`',
+    'False': ':data:`python:False`',
+    'list': ':class:`python:list`',
+    'tuple': ':class:`python:tuple`',
+    'str': ':class:`python:str`',
+    'string': ':class:`python:str`',
+    'dict': ':class:`python:dict`',
+    'float': ':class:`python:float`',
+    'int': ':class:`python:int`',
+    'callable': ':func:`callable <python:callable>`',
+    'iterable': ':term:`python:iterable`',
+    'contextmanager': ':func:`python:contextlib.contextmanager`',
+    'namedtuple': ':func:`python:collections.namedtuple`',
+    'generator': ':term:`python:generator`',
+    # NumPy
+    'array': '~numpy.ndarray',
+    'ndarray': '~numpy.ndarray',
+    'np.ndarray': '~numpy.ndarray',
+    'array-like': ':term:`numpy:array_like`',
+    'array_like': ':term:`numpy:array_like`',
+    'scalar': ':ref:`scalar <numpy:arrays.scalars>`',
+    'RandomState': '~numpy.random.RandomState',
+    'np.random.RandomState': '~numpy.random.RandomState',
+    'np.inf': ':data:`~numpy.inf`',
+    # 'numpy': ':mod:`numpy`',
+    # Matplotlib
+    'colormap': ':doc:`colormap <matplotlib:tutorials/colors/colormaps>`',
+    'color': ':doc:`color <matplotlib:api/colors_api>`',
+    'collection': ':doc:`collections <matplotlib:api/collections_api>`',
+    'Axes': '~matplotlib.axes.Axes',
+    'Figure': '~matplotlib.figure.Figure',
+    'Axes3D': '~mpl_toolkits.mplot3d.axes3d.Axes3D',
+    # Mayavi
+    'mayavi.mlab.Figure': 'mayavi.core.api.Scene',
+    'mlab.Figure': 'mayavi.core.api.Scene',
+    # sklearn
+    'LeaveOneOut': '~sklearn.model_selection.LeaveOneOut',
+    'sklearn.model_selection': ':mod:`sklearn.model_selection`',
+    # nibabel
+    'Nifti1Image': '~nibabel.nifti1.Nifti1Image',
+    'Nifti2Image': '~nibabel.nifti2.Nifti2Image',
+    # MNE
+    'Label': '~mne.Label', 'Forward': '~mne.Forward', 'Evoked': '~mne.Evoked',
+    'Info': '~mne.Info', 'SourceSpaces': '~mne.SourceSpaces',
+    'Epochs': '~mne.Epochs', 'Layout': '~mne.channels.Layout',
+    'EvokedArray': '~mne.EvokedArray', 'BiHemiLabel': '~mne.BiHemiLabel',
+    'AverageTFR': '~mne.time_frequency.AverageTFR',
+    'EpochsTFR': '~mne.time_frequency.EpochsTFR',
+    'Raw': '~mne.io.Raw', 'ICA': '~mne.preprocessing.ICA',
+    'Covariance': '~mne.Covariance', 'Annotations': '~mne.Annotations',
+    'Montage': '~mne.channels.Montage',
+    'DigMontage': '~mne.channels.DigMontage',
+    'VectorSourceEstimate': '~mne.VectorSourceEstimate',
+    'VolSourceEstimate': '~mne.VolSourceEstimate',
+    'MixedSourceEstimate': '~mne.MixedSourceEstimate',
+    'SourceEstimate': '~mne.SourceEstimate', 'Projection': '~mne.Projection',
+    'ConductorModel': '~mne.bem.ConductorModel',
+    'Dipole': '~mne.Dipole', 'DipoleFixed': '~mne.DipoleFixed',
+    'InverseOperator': '~mne.minimum_norm.InverseOperator',
+    'CrossSpectralDensity': '~mne.time_frequency.CrossSpectralDensity',
+    'RtEpochs': '~mne.realtime.RtEpochs',
+    'SourceMorph': '~mne.SourceMorph',
+    'Xdawn': '~mne.preprocessing.Xdawn',
+    'Report': '~mne.Report', 'Forward': '~mne.Forward',
+    'TimeDelayingRidge': '~mne.decoding.TimeDelayingRidge',
+    'Vectorizer': '~mne.decoding.Vectorizer',
+    'UnsupervisedSpatialFilter': '~mne.decoding.UnsupervisedSpatialFilter',
+    'TemporalFilter': '~mne.decoding.TemporalFilter',
+    'Scaler': '~mne.decoding.Scaler', 'SPoC': '~mne.decoding.SPoC',
+    'PSDEstimator': '~mne.decoding.PSDEstimator',
+    'LinearModel': '~mne.decoding.LinearModel',
+    'FilterEstimator': '~mne.decoding.FilterEstimator',
+    'EMS': '~mne.decoding.EMS', 'CSP': '~mne.decoding.CSP',
+    'Beamformer': '~mne.beamformer.Beamformer',
+}
+numpydoc_xref_ignore = {
+    # words
+    'instance', 'instances', 'of', 'default', 'shape', 'or',
+    'with', 'length', 'pair', 'matplotlib', 'optional', 'kwargs', 'in',
+    'dtype', 'object', 'self.verbose',
+    # shapes
+    'n_vertices', 'n_faces', 'n_channels', 'm', 'n', 'n_events', 'n_colors',
+    'n_times', 'obj', 'n_chan', 'n_epochs', 'n_picks', 'n_ch_groups',
+    'n_dipoles', 'n_ica_components', 'n_pos', 'n_node_names', 'n_tapers',
+    'n_signals', 'n_step', 'n_freqs', 'wsize', 'Tx', 'M', 'N', 'p', 'q',
+    'n_observations', 'n_regressors', 'n_cols', 'n_frequencies', 'n_tests',
+    'n_samples', 'n_permutations', 'nchan', 'n_points', 'n_features',
+    'n_parts', 'n_features_new', 'n_components', 'n_labels', 'n_events_in',
+    'n_splits', 'n_scores', 'n_outputs', 'n_trials', 'n_estimators', 'n_tasks',
+    'nd_features', 'n_classes', 'n_targets', 'n_slices', 'n_hpi', 'n_fids',
+    'n_elp', 'n_pts', 'n_tris',
+    # Undocumented (on purpose)
+    'RawKIT', 'RawEximia', 'RawEGI', 'RawEEGLAB', 'RawEDF', 'RawCTF', 'RawBTi',
+    'RawBrainVision',
+    # sklearn subclasses
+    'mapping', 'to', 'any',
+    # unlinkable
+    'mayavi.mlab.pipeline.surface',
+}
diff --git a/mne/annotations.py b/mne/annotations.py
@@ -37,7 +37,7 @@ class Annotations(object):
         Array of strings containing description for each annotation. If a
         string, all the annotations are given the same description. To reject
         epochs, use description starting with keyword 'bad'. See example above.
-    orig_time : float | int | instance of datetime | array of int | None | str
+    orig_time : float | int | instance of datetime.datetime | array of int | None | str
         A POSIX Timestamp, datetime or an array containing the timestamp as the
         first element and microseconds as the second element. Determines the
         starting time of annotation acquisition. If None (default),
@@ -764,7 +764,7 @@ def events_from_annotations(raw, event_id=None, regexp=None, use_rounding=True,
     ----------
     raw : instance of Raw
         The raw data for which Annotations are defined.
-    event_id : dict | Callable | None
+    event_id : dict | callable | None
         Dictionary of string keys and integer values as used in mne.Epochs
         to map annotation descriptions to integer event codes. Only the
         keys present will be mapped and the annotations with other descriptions

diff --git a/mne/beamformer/_dics.py b/mne/beamformer/_dics.py
@@ -641,11 +641,11 @@ def tf_dics(epochs, forward, noise_csds, tmin, tmax, tstep, win_lengths,
         tf source grid. Defaults to False.
     mode : 'fourier' | 'multitaper' | 'cwt_morlet'
         Spectrum estimation mode. Defaults to 'fourier'.
-    freq_bins : list of tuples of float
+    freq_bins : list of tuple of float
         Start and end point of frequency bins of interest.
         Only used in 'multitaper' or 'fourier' mode. For 'cwt_morlet' mode, use
         the ``frequencies`` parameter instead.
-    frequencies : list of float | list of lists of float
+    frequencies : list of float | list of list of float
         The frequencies to compute the source power for. If you want to compute
         the average power for multiple frequency bins, specify a list of
         lists: each list containing the frequencies for the corresponding bin.

diff --git a/mne/beamformer/_lcmv.py b/mne/beamformer/_lcmv.py
@@ -531,7 +531,7 @@ def tf_lcmv(epochs, forward, noise_covs, tmin, tmax, tstep, win_lengths,
     win_lengths : list of float
         Time window lengths in seconds. One time window length should be
         provided for each frequency bin.
-    freq_bins : list of tuples of float
+    freq_bins : list of tuple of float
         Start and end point of frequency bins of interest.
     subtract_evoked : bool
         If True, subtract the averaged evoked response prior to computing the

diff --git a/mne/channels/channels.py b/mne/channels/channels.py
@@ -524,7 +524,7 @@ def plot_sensors(self, kind='topomap', ch_type=None, title=None,
         show_names : bool | array of str
             Whether to display all channel names. If an array, only the channel
             names in the array are shown. Defaults to False.
-        ch_groups : 'position' | array of shape (ch_groups, picks) | None
+        ch_groups : 'position' | array of shape (n_ch_groups, n_picks) | None
             Channel groups for coloring the sensors. If None (default), default
             coloring scheme is used. If 'position', the sensors are divided
             into 8 regions. See ``order`` kwarg of :func:`mne.viz.plot_raw`. If
@@ -556,7 +556,7 @@ def plot_sensors(self, kind='topomap', ch_type=None, title=None,
 
         Returns
         -------
-        fig : instance of matplotlib figure
+        fig : instance of Figure
             Figure containing the sensor topography.
         selection : list
             A list of selected channels. Only returned if ``kind=='select'``.
@@ -1053,7 +1053,7 @@ def read_ch_connectivity(fname, picks=None):
 
     Returns
     -------
-    ch_connectivity : scipy.sparse matrix, shape (n_channels, n_channels)
+    ch_connectivity : scipy.sparse.csr_matrix, shape (n_channels, n_channels)
         The connectivity matrix.
     ch_names : list
         The list of channel names present in connectivity matrix.
@@ -1161,7 +1161,7 @@ def find_ch_connectivity(info, ch_type):
 
     Returns
     -------
-    ch_connectivity : scipy.sparse matrix, shape (n_channels, n_channels)
+    ch_connectivity : scipy.sparse.csr_matrix, shape (n_channels, n_channels)
         The connectivity matrix.
     ch_names : list
         The list of channel names present in connectivity matrix.
@@ -1388,7 +1388,7 @@ def make_1020_channel_selections(info, midline="z"):
 
     Parameters
     ----------
-    info : instance of info
+    info : instance of Info
         Where to obtain the channel names from. The picks will
         be in relation to the position in `info["ch_names"]`. If possible, this
         lists will be sorted by y value position of the channel locations,

diff --git a/mne/channels/layout.py b/mne/channels/layout.py
@@ -101,7 +101,7 @@ def plot(self, picks=None, show=True):
 
         Returns
         -------
-        fig : instance of matplotlib figure
+        fig : instance of matplotlib.figure.Figure
             Figure containing the sensor topography.
 
         Notes
@@ -913,7 +913,7 @@ def generate_2d_layout(xy, w=.07, h=.05, pad=.02, ch_names=None,
 
     Parameters
     ----------
-    xy : ndarray (N x 2)
+    xy : ndarray, shape (N, 2)
         The xy coordinates of sensor locations.
     w : float
         The width of each sensor's axis (between 0 and 1)
@@ -928,7 +928,7 @@ def generate_2d_layout(xy, w=.07, h=.05, pad=.02, ch_names=None,
     ch_indices : list
         Index of each channel - must be a collection of unique integers,
         one index per channel.
-    name : string
+    name : str
         The name of this layout type.
     bg_image : str | ndarray
         The image over which sensor axes will be plotted. Either a path to an

diff --git a/mne/connectivity/effective.py b/mne/connectivity/effective.py
@@ -49,20 +49,20 @@ def phase_slope_index(data, indices=None, sfreq=2 * np.pi,
         e.g., data = [(arr_0, stc_0), (arr_1, stc_1), (arr_2, stc_2)],
         corresponds to 3 epochs, and arr_* could be an array with the same
         number of time points as stc_*.
-    indices : tuple of arrays | None
+    indices : tuple of array | None
         Two arrays with indices of connections for which to compute
         connectivity. If None, all connections are computed.
     sfreq : float
         The sampling frequency.
     mode : str
         Spectrum estimation mode can be either: 'multitaper', 'fourier', or
         'cwt_morlet'.
-    fmin : float | tuple of floats
+    fmin : float | tuple of float
         The lower frequency of interest. Multiple bands are defined using
         a tuple, e.g., (8., 20.) for two bands with 8Hz and 20Hz lower freq.
         If None the frequency corresponding to an epoch length of 5 cycles
         is used.
-    fmax : float | tuple of floats
+    fmax : float | tuple of float
         The upper frequency of interest. Multiple bands are dedined using
         a tuple, e.g. (13., 30.) for two band with 13Hz and 30Hz upper freq.
     tmin : float | None

diff --git a/mne/connectivity/spectral.py b/mne/connectivity/spectral.py
@@ -649,20 +649,20 @@ def spectral_connectivity(data, method='coh', indices=None, sfreq=2 * np.pi,
         or a list/generator of SourceEstimate or VolSourceEstimate objects.
     method : string | list of string
         Connectivity measure(s) to compute.
-    indices : tuple of arrays | None
+    indices : tuple of array | None
         Two arrays with indices of connections for which to compute
         connectivity. If None, all connections are computed.
     sfreq : float
         The sampling frequency.
     mode : str
         Spectrum estimation mode can be either: 'multitaper', 'fourier', or
         'cwt_morlet'.
-    fmin : float | tuple of floats
+    fmin : float | tuple of float
         The lower frequency of interest. Multiple bands are defined using
         a tuple, e.g., (8., 20.) for two bands with 8Hz and 20Hz lower freq.
         If None the frequency corresponding to an epoch length of 5 cycles
         is used.
-    fmax : float | tuple of floats
+    fmax : float | tuple of float
         The upper frequency of interest. Multiple bands are dedined using
         a tuple, e.g. (13., 30.) for two band with 13Hz and 30Hz upper freq.
     fskip : int
@@ -707,7 +707,7 @@ def spectral_connectivity(data, method='coh', indices=None, sfreq=2 * np.pi,
 
     Returns
     -------
-    con : array | list of arrays
+    con : array | list of array
         Computed connectivity measure(s). The shape of each array is either
         (n_signals, n_signals, n_freqs) mode: 'multitaper' or 'fourier'
         (n_signals, n_signals, n_freqs, n_times) mode: 'cwt_morlet'

diff --git a/mne/connectivity/utils.py b/mne/connectivity/utils.py
@@ -28,7 +28,7 @@ def seed_target_indices(seeds, targets):
 
     Returns
     -------
-    indices : tuple of arrays
+    indices : tuple of array
         The indices parameter used for connectivity computation.
     """
     # make them arrays

diff --git a/mne/cov.py b/mne/cov.py
@@ -374,7 +374,7 @@ def compute_raw_covariance(raw, tmin=0, tmax=None, tstep=0.2, reject=None,
         See :func:`mne.compute_covariance`.
 
         .. versionadded:: 0.12
-    cv : int | sklearn model_selection object (default 3)
+    cv : int | sklearn.model_selection object (default 3)
         The cross validation method. Defaults to 3, which will
         internally trigger by default :class:`sklearn.model_selection.KFold`
         with 3 splits.
@@ -605,7 +605,7 @@ def compute_covariance(epochs, keep_sample_mean=True, tmin=None, tmax=None,
 
     Parameters
     ----------
-    epochs : instance of Epochs, or a list of Epochs objects
+    epochs : instance of Epochs, or list of Epochs
         The epochs.
     keep_sample_mean : bool (default True)
         If False, the average response over epochs is computed for
@@ -651,7 +651,7 @@ def compute_covariance(epochs, keep_sample_mean=True, tmin=None, tmax=None,
              'pca': {'iter_n_components': None},
              'factor_analysis': {'iter_n_components': None}}
 
-    cv : int | sklearn model_selection object (default 3)
+    cv : int | sklearn.model_selection object (default 3)
         The cross validation method. Defaults to 3, which will
         internally trigger by default :class:`sklearn.model_selection.KFold`
         with 3 splits.
@@ -1532,7 +1532,7 @@ def regularize(cov, info, mag=0.1, grad=0.1, eeg=0.1, exclude='bads',
     exclude : list | 'bads' (default 'bads')
         List of channels to mark as bad. If 'bads', bads channels
         are extracted from both info['bads'] and cov['bads'].
-    proj : bool (default true)
+    proj : bool (default True)
         Apply projections to keep rank of data.
     seeg : float (default 0.1)
         Regularization factor for sEEG signals.