MRG: Add links for parameters (#5840)

* ENH: Add links for parameters

* FIX: Heisenbug

Author: larsoner

.circleci/config.yml

@@ -56,6 +56,7 @@ jobs:
 
         - run:
             name: Get Anaconda running
+            # pip install --user --upgrade --progress-bar off https://api.github.com/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;

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;
+}

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',
+}

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

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.

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

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,

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

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

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'