Skip to content

Conversation

@larsoner
Copy link
Member

@larsoner larsoner commented Nov 12, 2018

This PR:

  1. Converts manual/decoding.rst into a tutorial by folding it and examples/decoding/plot_decoding_csp_space.py into tutorials/plot_sensors_decoding.py
  2. Makes our doc building strict about warnings so we stop producing broken links that need to be fixed at release time
  3. Removes an image from the channel interpolation doc that did not add much understanding (and in partial builds produces a warning)
  4. Fixes the @deprecated decorator to properly set the number of spaces to avoid a build warning
  5. Improves conf.py to turn warnings into errors during example runs (we should not have un-caught warnings in examples)
  6. Various minor fixes for doc building to avoid warnings

@larsoner larsoner added this to the 0.17 milestone Nov 12, 2018
@larsoner
Copy link
Member Author

@codecov
Copy link

codecov bot commented Nov 12, 2018

Codecov Report

Merging #5707 into master will decrease coverage by <.01%.
The diff coverage is 80%.

@@            Coverage Diff             @@
##           master    #5707      +/-   ##
==========================================
- Coverage   88.61%   88.61%   -0.01%     
==========================================
  Files         369      369              
  Lines       69463    69462       -1     
  Branches    11678    11678              
==========================================
- Hits        61557    61556       -1     
  Misses       5055     5055              
  Partials     2851     2851

@massich
Copy link
Contributor

massich commented Nov 13, 2018

I build it locally with make html_dev-noplot and I got these warnings:

/home/sik/code/mne-python/doc/auto_tutorials/plot_morph_stc.rst:115: WARNING: image file not readable: auto_tutorials/../../_images/sphx_glr_plot_morph_volume_stc_001.png
/home/sik/code/mne-python/doc/auto_tutorials/plot_morph_stc.rst:251: WARNING: image file not readable: auto_tutorials/../../_images/sphx_glr_plot_morph_surface_stc_001.png
/home/sik/code/mne-python/mne/source_estimate.py:docstring of mne.SourceEstimate.morph:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/sik/code/mne-python/mne/source_estimate.py:docstring of mne.SourceEstimate.morph_precomputed:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/sik/code/mne-python/mne/source_estimate.py:docstring of mne.VectorSourceEstimate.morph:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/sik/code/mne-python/mne/source_estimate.py:docstring of mne.VectorSourceEstimate.morph_precomputed:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/sik/code/mne-python/doc/manual/channel_interpolation.rst:: WARNING: image file not readable: manual/../../_images/sphx_glr_plot_interpolate_bad_channels_002.png
/home/sik/code/mne-python/doc/manual/decoding.rst:: WARNING: image file not readable: manual/../../_images/sphx_glr_plot_linear_model_patterns_001.png
/home/sik/code/mne-python/doc/manual/decoding.rst:: WARNING: image file not readable: manual/../../_images/sphx_glr_plot_linear_model_patterns_002.png
/home/sik/code/mne-python/doc/manual/decoding.rst:: WARNING: image file not readable: manual/../../_images/sphx_glr_plot_sensors_decoding_001.png
/home/sik/code/mne-python/doc/manual/decoding.rst:: WARNING: image file not readable: manual/../../_images/sphx_glr_plot_sensors_decoding_004.png
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] whats_new                                                                                                                     
/home/sik/code/mne-python/doc/whats_new.rst:108: WARNING: py:func reference target not found: mne.beamformer.make_lcmv`

But circle passes without issue.

@larsoner
Copy link
Member Author

I don't see it locally either, maybe you need a newer numpydoc or sphinx

@massich
Copy link
Contributor

massich commented Nov 13, 2018

Actually, I mess up. It was my fault.

@massich
Copy link
Contributor

massich commented Nov 13, 2018

But I'm trying to compile it now, and it fails with this packages

sphinx 1.7.6 py36_0
sphinx-bootstrap-theme 0.6.5
sphinx-fontawesome 0.0.6
sphinx-gallery 0.2.0
sphinxcontrib 1.0 py36_1
sphinxcontrib-websupport 1.1.0 py36_1

~/code/mne-python/doc doc*
(mne) ❯ make html_dev-noplot 
BUILD_DEV_HTML=1 sphinx-build -D plot_gallery=0 -b html -d _build/doctrees  -n -W -T --keep-going . _build/html
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
sphinx-build: error: unrecognized arguments: --keep-going
Makefile:60: recipe for target 'html_dev-noplot' failed
make: *** [html_dev-noplot] Error 2

It does not like the keep going. So we need sphinx==1.8

@massich
Copy link
Contributor

massich commented Nov 13, 2018

This is my log:

~/code/mne-python/doc doc* 15s
(mne) ❯ make html_dev-noplot                                                                          
BUILD_DEV_HTML=1 sphinx-build -D plot_gallery=0 -b html -d _build/doctrees  -n -W -T --keep-going . _build/html
Running Sphinx v1.8.1
loading pickled environment... failed: build environment version not current
[autosummary] generating autosummary for: advanced_setup.rst, auto_examples/connectivity/plot_cwt_sensor_connectivity.rst, auto_examples/connectivity/plot_mixed_source_space_connectivity.rst, auto_examples/connectivity/plot_mne_inverse_coherence_epochs.rst, auto_examples/connectivity/plot_mne_inverse_connectivity_spectrum.rst, auto_examples/connectivity/plot_mne_inverse_label_connectivity.rst, auto_examples/connectivity/plot_mne_inverse_psi_visual.rst, auto_examples/connectivity/plot_sensor_connectivity.rst, auto_examples/datasets/plot_brainstorm_data.rst, auto_examples/datasets/plot_hf_sef_data.rst, ..., manual/time_frequency.rst, manual/visualization.rst, martinos.rst, mne_cpp.rst, python_reference.rst, references.rst, tutorials/command_line.rst, tutorials/philosophy.rst, tutorials/report.rst, whats_new.rst
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://www.numpy.org/devdocs/objects.inv...
loading intersphinx inventory from https://scipy.github.io/devdocs/objects.inv...
loading intersphinx inventory from https://matplotlib.org/objects.inv...
loading intersphinx inventory from https://scikit-learn.org/stable/objects.inv...
loading intersphinx inventory from http://docs.enthought.com/mayavi/mayavi/objects.inv...
loading intersphinx inventory from http://nipy.org/nibabel/objects.inv...
loading intersphinx inventory from http://nilearn.github.io/objects.inv...
loading intersphinx inventory from https://pysurfer.github.io/objects.inv...
loading intersphinx inventory from https://pandas.pydata.org/pandas-docs/stable/objects.inv...
loading intersphinx inventory from http://www.statsmodels.org/stable/objects.inv...
loading intersphinx inventory from http://nipy.org/dipy/objects.inv...
generating gallery...
generating gallery for auto_examples/connectivity... [100%] plot_mixed_source_space_connectivity.py                                      
generating gallery for auto_examples/datasets... [100%] plot_opm_rest_data.py                                                            
generating gallery for auto_examples/decoding... [100%] plot_receptive_field_mtrf.py                                                     
generating gallery for auto_examples/forward... [100%] plot_left_cerebellum_volume_source.py                                             
generating gallery for auto_examples/inverse... [100%] plot_tf_lcmv.py                                                                   
generating gallery for auto_examples/io... [100%] plot_objects_from_arrays.py                                                            
generating gallery for auto_examples/preprocessing... [100%] plot_define_target_events.py                                                
generating gallery for auto_examples/realtime... [100%] rt_feedback_server.py                                                            
generating gallery for auto_examples/simulation... [100%] plot_simulate_raw_data.py                                                      
generating gallery for auto_examples/stats... [100%] plot_cluster_stats_evoked.py                                                        
generating gallery for auto_examples/time_frequency... [100%] plot_time_frequency_simulated.py                                           
generating gallery for auto_examples/visualization... [100%] plot_3d_to_2d.py                                                            
generating gallery for auto_tutorials... [100%] plot_background_filtering.py                                                             
generating MNE command help ... [100%] mne_browse_raw.py                                                                                 
[Done]
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 636 source files that are out of date
updating environment: 636 added, 0 changed, 0 removed
reading sources... [100%] whats_new                                                                                                      
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/sik/code/mne-python/doc/auto_examples/decoding/plot_decoding_csp_space.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
/home/sik/miniconda3/envs/mne/lib/python3.6/site-packages/sphinx/builders/html.py:130: RemovedInSphinx20Warning: builder.css_files is deprecated. Please use app.add_stylesheet() instead.
  RemovedInSphinx20Warning)
writing output... [100%] whats_new                                                                                                       
generating indices... genindex py-modindex
writing additional pages... search
copying images... [100%] tutorials/mne-report.png                                                                                        
copying downloadable files... [100%] auto_tutorials/plot_whitened.ipynb                                                                  
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build finished with problems, 1 warning.
embedding documentation hyperlinks...
embedding documentation hyperlinks for auto_examples... [100%] plot_sensor_regression.html                                               
embedding documentation hyperlinks for auto_tutorials... [100%] plot_brainstorm_auditory.html                                            
Makefile:60: recipe for target 'html_dev-noplot' failed
make: *** [html_dev-noplot] Error 1

@larsoner
Copy link
Member Author

make clean then try again

@massich
Copy link
Contributor

massich commented Nov 13, 2018

yes! my bad. I had a messy tree.

@larsoner
Copy link
Member Author

Yes the warning about a file that does not exist in this branch was the clue :)

@mmagnuski
Copy link
Member

The tutorial looks great!
One tiny nitpick is that this warning box color makes it hard to read the object name:
image
moreover, if we agree on the warning content it should be also mentioned in mne.decoding.FilterEstimator docs too. Last, if one knows what they are doing and is careful about epoch length do we still discourage the usage of FilterEstimator?

@agramfort
Copy link
Member

agramfort commented Nov 13, 2018 via email

@larsoner
Copy link
Member Author

if we agree on the warning content it should be also mentioned in mne.decoding.FilterEstimator docs too. Last, if one knows what they are doing and is careful about epoch length do we still discourage the usage of FilterEstimator?

Yes, so I've moved the warning to the FilterEstimator class and made it less stringent

@larsoner
Copy link
Member Author

Forthcoming commit will also improve things by turning warnings during example runs into errors, so that our examples in doc building should (become, with these changes, and from here on out) stay clean

@larsoner
Copy link
Member Author

Okay CIs are finally green and I think I've addressed all comments. Okay to merge @agramfort ?

@larsoner
Copy link
Member Author

I'll actually go ahead and merge and we can tweak docs further if we need to for release (hopefully in the next couple of days!)

@larsoner larsoner merged commit 908ef20 into mne-tools:master Nov 14, 2018
@larsoner larsoner deleted the doc branch November 14, 2018 15:57

# Now we create a mixed src space by adding the volume regions specified in the
# list labels_vol. First, read the aseg file and the source space bounds
# using the inner skull surface (here using 10mm spacing to save time):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry to be a bit later here but I am afraid people with just copy paste these defaults which are here due to running time. Can you make more explicit that oct5 and pos=10 are not recommended for real analysis? thx

@massich
Copy link
Contributor

massich commented Nov 14, 2018

-- edit --- wrong PR.
message moved to #5712 (comment)

@larsoner
Copy link
Member Author

larsoner commented Nov 14, 2018

edit: (moved)

@larsoner larsoner mentioned this pull request Nov 15, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants