MRG: Improve decoding doc and sphinx process

.circleci/config.yml

@@ -28,6 +28,7 @@ jobs:
         # Spin up Xvfb
         - run: /sbin/start-stop-daemon --start --quiet --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background --exec /usr/bin/Xvfb -- :99 -screen 0 1400x900x24 -ac +extension GLX +render -noreset;
         - run: echo "export DISPLAY=:99" >> $BASH_ENV;
+        - run: echo "export OPENBLAS_NUM_THREADS=1" >> $BASH_ENV;
         # Fix libgcc_s.so.1 pthread_cancel bug:
         # https://github.com/ContinuumIO/anaconda-issues/issues/9190#issuecomment-386508136
         # https://github.com/golemfactory/golem/issues/1019
@@ -45,7 +46,7 @@ jobs:
               conda env create --quiet -f environment.yml;
               source activate mne;
               conda install sphinx;
-              pip install sphinx_fontawesome sphinx_bootstrap_theme "https://github.com/ghapi/repos/sphinx-gallery/sphinx-gallery/zipball/master"
+              pip install sphinx_fontawesome sphinx_bootstrap_theme "https://github.com/ghapi/repos/sphinx-gallery/sphinx-gallery/zipball/master" memory_profiler
               pip uninstall --yes mne;
               echo "source activate mne" >> $BASH_ENV;
         - save_cache:

.mailmap

@@ -112,3 +112,6 @@ Erik Hornberger <erik.hornberger@shi-g.com> er06645810 <erik.hornberger@shi-g.co
 Kostiantyn Maksymenko <makkostya@ukr.net> Maksymenko Kostiantyn <makkostya@ukr.net>
 Nathalie Gayraud <nathalie.gayraud@inria.fr> Nathalie <nathalie.gayraud@inria.fr>
 Dominik Krzemiński <raymon92@gmail.com> dokato <raymon92@gmail.com>
+Ezequiel Mikulan <39155887+ezemikulan@users.noreply.github.com> ezemikulan <39155887+ezemikulan@users.noreply.github.com>
+Hubert Banville <hubert.jbanville@gmail.com> hubertjb <hubert.jbanville@gmail.com>
+Sara Sommariva <sommariva@dima.unige.it> sarasommariva <sommariva@dima.unige.it>

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -n -W -T --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 
@@ -33,13 +33,7 @@ help:
 	@echo "  doctest          to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf _build/*
-	-rm -rf auto_examples
-	-rm -rf auto_tutorials
-	-rm -rf generated
-	-rm -rf *.stc
-	-rm -rf *.fif
-	-rm -rf *.nii.gz
+	-rm -rf _build/* auto_examples auto_tutorials generated *.stc *.fif *.nii.gz
 
 html_stable:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html_stable

doc/carousel.inc

@@ -36,7 +36,7 @@
           </div>
 
           <div class="item">
-            <div class="chopper container"><img src="_images/sphx_glr_plot_sensors_decoding_004.png" alt="Decoding" class="carousel-image"></div>
+            <div class="chopper container"><img src="_images/sphx_glr_plot_sensors_decoding_006.png" alt="Decoding" class="carousel-image"></div>
             <div class="container">
               <div class="carousel-caption">
                 <h2>Machine learning</h2>

doc/conf.py

@@ -12,18 +12,24 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import inspect
+from datetime import date
+from distutils.version import LooseVersion
 import os
-from os.path import relpath, dirname
 import sys
-from datetime import date
-import sphinx_gallery  # noqa
+import warnings
+
+import sphinx_gallery
+from sphinx_gallery.sorting import FileNameSortKey
 import sphinx_bootstrap_theme
 from numpydoc import numpydoc, docscrape  # noqa
 import sphinx_fontawesome
 import mne
 from mne.utils import linkcode_resolve  # noqa, analysis:ignore
 
+if LooseVersion(sphinx_gallery.__version__) < LooseVersion('0.2'):
+    raise ImportError('Must have at least version 0.2 of sphinx-gallery, got '
+                      '%s' % (sphinx_gallery.__version__,))
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -37,7 +43,7 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.8'
 
 # XXX This hack defines what extra methods numpydoc will document
 docscrape.ClassDoc.extra_public_methods = mne.utils._doc_special_members
@@ -61,7 +67,7 @@
 ]
 
 autosummary_generate = True
-autodoc_default_flags = ['inherited-members']
+autodoc_default_options = {'inherited-members': None}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -285,7 +291,7 @@
     'numpy': ('https://www.numpy.org/devdocs', None),
     'scipy': ('https://scipy.github.io/devdocs', None),
     'matplotlib': ('https://matplotlib.org', None),
-    'sklearn': ('http://scikit-learn.org/stable', None),
+    'sklearn': ('https://scikit-learn.org/stable', None),
     'mayavi': ('http://docs.enthought.com/mayavi/mayavi', None),
     'nibabel': ('http://nipy.org/nibabel', None),
     'nilearn': ('http://nilearn.github.io', None),
@@ -300,28 +306,75 @@
 
 try:
     mlab = mne.utils._import_mlab()
-    find_mayavi_figures = True
     # Do not pop up any mayavi windows while running the
     # examples. These are very annoying since they steal the focus.
     mlab.options.offscreen = True
+    scrapers = ('matplotlib', 'mayavi')
 except Exception:
-    find_mayavi_figures = False
-
+    scrapers = ('matplotlib',)
+else:
+    # Let's do the same thing we do in tests: reraise traits exceptions
+    from traits.api import push_exception_handler
+    push_exception_handler(reraise_exceptions=True)
+
+
+def reset_warnings(gallery_conf, fname):
+    """Ensure we are future compatible and ignore silly warnings."""
+    # In principle, our examples should produce no warnings.
+    # Here we cause warnings to become errors, with a few exceptions.
+    # This list should be considered alongside
+    # setup.cfg -> [tool:pytest] -> filterwarnings
+
+    # remove tweaks from other module imports or example runs
+    warnings.resetwarnings()
+    # restrict
+    warnings.filterwarnings('error')
+    # allow these, but show them
+    warnings.filterwarnings('always', '.*cannot make axes width small.*')
+    warnings.filterwarnings('always', '.*Axes that are not compatible.*')
+    warnings.filterwarnings('always', '.*FastICA did not converge.*')
+    warnings.filterwarnings(  # xhemi morph (should probably update sample)
+        'always', '.*does not exist, creating it and saving it.*')
+    warnings.filterwarnings('default', module='sphinx')  # internal warnings
+    warnings.filterwarnings(
+        'always', '.*converting a masked element to nan.*')  # matplotlib?
+    # allow these warnings, but don't show them
+    warnings.filterwarnings('ignore', '.*is currently using agg.*')
+    warnings.filterwarnings(  # SciPy-related warning (maybe 1.2.0 will fix it)
+        'ignore', '.*the matrix subclass is not the recommended.*')
+    warnings.filterwarnings(  # some joblib warning
+        'ignore', '.*semaphore_tracker: process died unexpectedly.*')
+    warnings.filterwarnings(  # needed until SciPy 1.2.0 is released
+        'ignore', '.*will be interpreted as an array index.*', module='scipy')
+    for key in ('HasTraits', r'numpy\.testing', 'importlib', r'np\.loads',
+                r"it will be an error for 'np\.bool_'",  # ndimage
+                "'U' mode is deprecated",  # sphinx io
+                ):
+        warnings.filterwarnings(  # deal with other modules having bad imports
+            'ignore', message=".*%s.*" % key, category=DeprecationWarning)
+    # allow this ImportWarning, but don't show it
+    warnings.filterwarnings(
+        'ignore', message="can't resolve package from", category=ImportWarning)
+
+
+reset_warnings(None, None)
 sphinx_gallery_conf = {
     'doc_module': ('mne',),
-    'reference_url': {
-        'mne': None,
-        },
+    'reference_url': dict(mne=None),
     'examples_dirs': examples_dirs,
     'gallery_dirs': gallery_dirs,
-    'find_mayavi_figures': find_mayavi_figures,
     'default_thumb_file': os.path.join('_static', 'mne_helmet.png'),
     'backreferences_dir': 'generated',
     'plot_gallery': 'True',  # Avoid annoying Unicode/bool default warning
     'download_section_examples': False,
     'thumbnail_size': (160, 112),
     'min_reported_time': 1.,
     'abort_on_example_error': False,
+    'reset_modules': ('matplotlib', reset_warnings),  # called w/each script
+    'image_scrapers': scrapers,
+    'show_memory': True,
+    'line_numbers': True,
+    'within_subsection_order': FileNameSortKey,
 }
 
 numpydoc_class_members_toctree = False

doc/contributing.rst

@@ -120,9 +120,14 @@ see `Sphinx documentation`_ to learn more about editing them. Our code
 follows the `NumPy docstring standard`_.
 
 Documentation is automatically built remotely during pull requests. If
-you want to also test documentation locally, you will need to install
-``sphinx sphinx-gallery sphinx_bootstrap_theme sphinx_fontawesome``, and then
-within the ``mne/doc`` directory do:
+you want to also test documentation locally, you will need to install (using
+``conda`` or ``pip`` as preferred):
+
+.. code-block:: console
+
+   $ pip install sphinx sphinx-gallery sphinx_bootstrap_theme sphinx_fontawesome memory_profiler
+
+and then within the ``mne/doc`` directory do:
 
 .. code-block:: console
 

doc/documentation.rst

@@ -553,7 +553,6 @@ There are also **examples**, which contain a short use-case to highlight MNE-fun
 .. toctree::
     :maxdepth: 1
 
-    manual/decoding.rst
     auto_tutorials/plot_sensors_decoding.rst
 
 .. raw:: html
@@ -566,7 +565,6 @@ There are also **examples**, which contain a short use-case to highlight MNE-fun
 
     auto_examples/decoding/decoding_rsa.rst
     auto_examples/decoding/plot_decoding_csp_eeg.rst
-    auto_examples/decoding/plot_decoding_csp_space.rst
     auto_examples/decoding/plot_decoding_csp_timefreq.rst
     auto_examples/decoding/plot_decoding_spatio_temporal_source.rst
     auto_examples/decoding/plot_decoding_spoc_CMC.rst

doc/manual/channel_interpolation.rst

@@ -60,11 +60,7 @@ To interpolate bad channels, one can simply do:
 
 	>>> evoked.interpolate_bads(reset_bads=False)  # doctest: +SKIP
 
-and the bad channel will be fixed
-
-.. image:: ../../_images/sphx_glr_plot_interpolate_bad_channels_002.png
-   :align: center
-   :height: 300 px
+and the bad channel will be fixed.
 
 .. topic:: Examples: