MRG: Better class doc (#6152)

larsoner · web-flow · commit ece75432a4d5 · 2019-04-15T15:05:44.000-04:00
diff --git a/Makefile b/Makefile
@@ -5,7 +5,7 @@
 PYTHON ?= python
 PYTESTS ?= py.test
 CTAGS ?= ctags
-CODESPELL_SKIPS ?= "*.fif,*.eve,*.gz,*.tgz,*.zip,*.mat,*.stc,*.label,*.w,*.bz2,*.annot,*.sulc,*.log,*.local-copy,*.orig_avg,*.inflated_avg,*.gii,*.pyc,*.doctree,*.pickle,*.inv,*.png,*.edf,*.touch,*.thickness,*.nofix,*.volume,*.defect_borders,*.mgh,lh.*,rh.*,COR-*,FreeSurferColorLUT.txt,*.examples,.xdebug_mris_calc,bad.segments,BadChannels,*.hist,empty_file,*.orig,*.js,*.map,*.ipynb,searchindex.dat,install_mne_c.rst,plot_*.rst,*.rst.txt,c_EULA.rst*,*.html"
+CODESPELL_SKIPS ?= "*.fif,*.eve,*.gz,*.tgz,*.zip,*.mat,*.stc,*.label,*.w,*.bz2,*.annot,*.sulc,*.log,*.local-copy,*.orig_avg,*.inflated_avg,*.gii,*.pyc,*.doctree,*.pickle,*.inv,*.png,*.edf,*.touch,*.thickness,*.nofix,*.volume,*.defect_borders,*.mgh,lh.*,rh.*,COR-*,FreeSurferColorLUT.txt,*.examples,.xdebug_mris_calc,bad.segments,BadChannels,*.hist,empty_file,*.orig,*.js,*.map,*.ipynb,searchindex.dat,install_mne_c.rst,plot_*.rst,*.rst.txt,c_EULA.rst*,*.html,gdf_encodes.txt"
 CODESPELL_DIRS ?= mne/ doc/ tutorials/ examples/
 all: clean inplace test test-doc
 
diff --git a/doc/_static/style.css b/doc/_static/style.css
@@ -351,3 +351,7 @@ dl.cmd-list dt, dl.cmd-list dd {
 dl.cmd-list dt::after {
     visibility: hidden;
 }
+/* Attributes / methods not taking up entire width ends up looking odd */
+dd table.align-center {
+    width: 100%;
+}
diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst
@@ -5,8 +5,6 @@
 
 .. autoclass:: {{ objname }}
    :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__,__hash__
-
-   {% block methods %}
-   {% endblock %}
+   :members:
 
 .. include:: {{module}}.{{objname}}.examples
diff --git a/doc/conf.py b/doc/conf.py
@@ -420,86 +420,58 @@ def reset_warnings(gallery_conf, fname):
 # 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_attributes_as_param_list = 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',
+    '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`',
+    'LeaveOneOut': 'sklearn.model_selection.LeaveOneOut',
     # nibabel
-    'Nifti1Image': '~nibabel.nifti1.Nifti1Image',
-    'Nifti2Image': '~nibabel.nifti2.Nifti2Image',
+    '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',
-    'VolVectorSourceEstimate': '~mne.VolVectorSourceEstimate',
-    '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',
+    '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',
+    'VolVectorSourceEstimate': 'mne.VolVectorSourceEstimate',
+    '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
@@ -516,7 +488,7 @@ def reset_warnings(gallery_conf, fname):
     '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', 'n_nodes', 'n_nonzero',
+    'n_elp', 'n_pts', 'n_tris', 'n_nodes', 'n_nonzero', 'n_events_out',
     # Undocumented (on purpose)
     'RawKIT', 'RawEximia', 'RawEGI', 'RawEEGLAB', 'RawEDF', 'RawCTF', 'RawBTi',
     'RawBrainVision',
diff --git a/doc/whats_new.rst b/doc/whats_new.rst
@@ -1506,7 +1506,7 @@ API
 
 - Weighted addition and subtraction of :class:`Evoked` as ``ev1 + ev2`` and ``ev1 - ev2`` have been deprecated, use explicit :func:`mne.combine_evoked(..., weights='nave') <mne.combine_evoked>` instead by `Eric Larson`_
 
-- Deprecated support for passing a lits of filenames to :class:`mne.io.Raw` constructor, use :func:`mne.io.read_raw_fif` and :func:`mne.concatenate_raws` instead by `Eric Larson`_
+- Deprecated support for passing a list of filenames to :class:`mne.io.Raw` constructor, use :func:`mne.io.read_raw_fif` and :func:`mne.concatenate_raws` instead by `Eric Larson`_
 
 - Added options for setting data and date formats manually in :func:`mne.io.read_raw_cnt` by `Jaakko Leppakangas`_
 
diff --git a/ignore_words.txt b/ignore_words.txt
@@ -20,3 +20,6 @@ thes
 ba
 ist
 theses
+od
+fo
+files'
diff --git a/mne/bem.py b/mne/bem.py
@@ -1339,8 +1339,10 @@ def read_bem_solution(fname, verbose=None):
 
     See Also
     --------
-    write_bem_solution, read_bem_surfaces, write_bem_surfaces,
+    read_bem_surfaces
+    write_bem_surfaces
     make_bem_solution
+    write_bem_solution
     """
     # mirrors fwd_bem_load_surfaces from fwd_bem_model.c
     logger.info('Loading surfaces...')
diff --git a/mne/channels/layout.py b/mne/channels/layout.py
@@ -227,7 +227,7 @@ def make_eeg_layout(info, radius=0.5, width=None, height=None, exclude='bads'):
         this will be the maximum width possible without axes overlapping.
     height : float | None
         Height of sensor axes as a fraction of main figure height. By default,
-        this will be the maximum height possible withough axes overlapping.
+        this will be the maximum height possible without axes overlapping.
     exclude : list of string | str
         List of channels to exclude. If empty do not exclude any.
         If 'bads', exclude channels in info['bads'] (default).
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
@@ -771,7 +771,7 @@ def fit(self, X, y):
         if len(np.unique(y)) < 2:
             raise ValueError("y must have at least two distinct values.")
 
-        # The following code is direclty copied from pyRiemann
+        # The following code is directly copied from pyRiemann
 
         # Normalize target variable
         target = y.astype(np.float64)
diff --git a/mne/event.py b/mne/event.py
@@ -749,7 +749,7 @@ def merge_events(events, ids, new_id, replace_events=True):
 
     Returns
     -------
-    new_events: array, shape (n_events_out, 3)
+    new_events : array, shape (n_events_out, 3)
         The new events
 
     Examples
diff --git a/mne/forward/_lead_dots.py b/mne/forward/_lead_dots.py
@@ -56,7 +56,7 @@ def _get_legen_table(ch_type, volume_integral=False, n_coeff=100,
         raise RuntimeError('n_interp must be even')
     fname = op.join(_get_extra_data_path(), 'tables')
     if not op.isdir(fname):
-        # Updated due to API chang (GH 1167)
+        # Updated due to API change (GH 1167)
         os.makedirs(fname)
     if ch_type == 'meg':
         fname = op.join(fname, 'legder_%s_%s.bin' % (n_coeff, n_interp))
diff --git a/mne/io/meas_info.py b/mne/io/meas_info.py
@@ -298,7 +298,7 @@ class Info(dict):
         unit : int
             The unit to use, e.g. ``FIFF_UNIT_T_M``.
         unit_mul : int
-            Unit multipliers, most commontly ``FIFF_UNITM_NONE``.
+            Unit multipliers, most commonly ``FIFF_UNITM_NONE``.
 
     * ``comps`` list of dict:
 
diff --git a/mne/minimum_norm/tests/test_inverse.py b/mne/minimum_norm/tests/test_inverse.py
@@ -511,7 +511,7 @@ def test_make_inverse_operator_fixed(evoked, noise_cov):
 
     # now compare to C solution
     # note that the forward solution must not be surface-oriented
-    # to get equivalency (surf_ori=True changes the normals)
+    # to get equivalence (surf_ori=True changes the normals)
     with catch_logging() as log:
         inv_op = make_inverse_operator(  # test depth=0. alias for depth=None
             evoked.info, fwd, noise_cov, depth=0., fixed=True,
diff --git a/mne/tests/test_report.py b/mne/tests/test_report.py
@@ -330,7 +330,7 @@ def test_open_report():
     # Exiting the context block should have triggered saving to HDF5
     assert op.exists(hdf5)
 
-    # Load the HDF5 version of the report and check equivalency
+    # Load the HDF5 version of the report and check equivalence
     report2 = open_report(hdf5)
     assert report2._fname == hdf5
     assert report2.subjects_dir == report.subjects_dir
diff --git a/tutorials/plot_background_filtering.py b/tutorials/plot_background_filtering.py
@@ -284,7 +284,7 @@
 # sample at each time point :math:`t` is filtered using samples that come
 # after (:math:`t + \Delta t`) *and* before (:math:`t - \Delta t`) :math:`t`.
 # In this sense, each sample is influenced by samples that come both before
-# and after it. This is useful in many cases, espcially because it does not
+# and after it. This is useful in many cases, especially because it does not
 # delay the timing of events.
 #
 # However, sometimes it can be beneficial to use *causal* filtering,

Original file line number	Diff line number	Diff line change
`@@ -351,3 +351,7 @@ dl.cmd-list dt, dl.cmd-list dd {`
`351`	`351`	`dl.cmd-list dt::after {`
`352`	`352`	`visibility: hidden;`
`353`	`353`	`}`
	`354`	`+/* Attributes / methods not taking up entire width ends up looking odd */`
	`355`	`+dd table.align-center {`
	`356`	`+ width: 100%;`
	`357`	`+}`
-Original file line number
+Diff line change
 ba
 ist
 theses
 +od
 +fo
 +files'