Fix notebook-style examples

[GaelVaroquaux]

Describe the issue linked to the documentation

Many legitimate notebook style examples have been broken, and specifically by the following PR
#9061

List of examples to update

Note for maintainers: the content between begin/end_auto_generated is updated automatically by a script. If you edit it by hand your changes may be reverted. The script doing the update: https://gist.github.com/lesteve/478d52599d394ec5e7f56dbf0827a5e9

Here are all the examples that use patterns like # ####### (found by ag -l '# #####*\s#' examples | sort, note there may be false positives ... for I removed examples/impute/plot_missing_values.py which is using # %% but also # #### as title underlines ...):

begin_auto_generated

• examples/applications/plot_prediction_latency.py DOC: use notebook-style in plot_prediction_latency.py #22418
• examples/applications/plot_stock_market.py DOC: use notebook-style for plot_stock_market.py #22461
• examples/applications/wikipedia_principal_eigenvector.py DOC: use notebook-style for wikipedia_principal_eigenvector.py #22704
• examples/calibration/plot_calibration.py DOC: update notebook-style for plot_calibration.py #22734
• examples/classification/plot_lda_qda.py DOC update notebook style for plot_lda_qda #22528
• examples/cluster/plot_affinity_propagation.py DOC: Update notebook-style example plot_affinity_propagation #22559
• examples/cluster/plot_coin_ward_segmentation.py DOC Fix notebook style of plot_coin_ward_segmentation #23164
• examples/cluster/plot_dbscan.py DOC: Update notebook-style example plot_dbscan #22568
• examples/cluster/plot_dict_face_patches.py DOC: Use notebook-style plot_dict_face_patches.py #22929
• examples/cluster/plot_feature_agglomeration_vs_univariate_selection.py DOC: use notebook-style for plot_feature_agglomeration_vs_univariate_selection.py #22796
• examples/cluster/plot_mean_shift.py DOC: use notebook-style for plot_mean_shift.py #22713
• examples/cluster/plot_mini_batch_kmeans.py DOC convert examples/cluster/plot_mini_batch_kmeans.py to notebook style #22900
• examples/cluster/plot_segmentation_toy.py DOC: Fixing notebook-style formatting on plot_segmentation_toy.py #23140
• examples/cluster/plot_ward_structured_vs_unstructured.py DOC: use notebook-style for plot_ward_structured_vs_unstructured.py #23228
• examples/covariance/plot_covariance_estimation.py DOC: use notebook-style for plot_covariance_estimation.py #23150
• examples/covariance/plot_sparse_cov.py DOC use notebook-style for plot_sparse_cov.py #22807
• examples/cross_decomposition/plot_compare_cross_decomposition.py DOC Use notebook style for remaining notebooks from notebook-style meta-issue #23365
• examples/decomposition/plot_faces_decomposition.py DOC use notebook-style for plot_faces_decomposition #22452
• examples/decomposition/plot_ica_blind_source_separation.py DOC Use notebook style for remaining notebooks from notebook-style meta-issue #23365
• examples/decomposition/plot_ica_vs_pca.py DOC: update notebook-style for plot_ica_vs_pca.py #23106
• examples/decomposition/plot_image_denoising.py DOC: Update notebook-style for example plot_image_denoising #22739
• examples/decomposition/plot_pca_3d.py DOC: use notebook-style for plot_pca_3d.py #23064
• examples/decomposition/plot_pca_vs_fa_model_selection.py Update plot_pca_vs_fa_model_selection.py #23148
• examples/exercises/plot_cv_diabetes.py DOC: update notebook-style example plot_cv_diabetes.py #22740
• examples/feature_selection/plot_feature_selection.py DOC use notebook-style for example plot_feature_selection.py #22437
• examples/linear_model/plot_ard.py DOC fix section marker in plot_ard.py examples #22481
• examples/linear_model/plot_bayesian_ridge_curvefit.py DOC Update notebook style for plot_bayesian_ridge_curvefit #22916
• examples/linear_model/plot_bayesian_ridge.py DOC Update notebook style for plot_bayesian_ridge_curvefit #22916 DOC use notebook-style for plot_bayesian_ridge.py #22794
• examples/linear_model/plot_lasso_and_elasticnet.py DOC use notebook-style for plot_lasso_and_elasticnet #22423
• examples/linear_model/plot_lasso_dense_vs_sparse_data.py DOC Use notebook style for plot_lasso_dense_vs_sparse_data #22789
• examples/linear_model/plot_logistic_path.py DOC: use notebook-style for plot_logistic_path.py #22536
• examples/linear_model/plot_multi_task_lasso_support.py DOC Use notebook style for remaining notebooks from notebook-style meta-issue #23365
• examples/linear_model/plot_ols_3d.py DOC: use notebook-style for plot_ols_3d #22547
• examples/linear_model/plot_ridge_path.py DOC use notebook-style in linear_model/plot_ridge_path.py #23209
• examples/linear_model/plot_theilsen.py DOC use notebook-style for plot_theilsen #23002
• examples/miscellaneous/plot_kernel_ridge_regression.py DOC Use notebook style in plot_kernel_ridge_regression.py #22804
• examples/model_selection/grid_search_text_feature_extraction.py DOC updated to notebook style for grid_search_text_feature_extraction.py #22558
• examples/model_selection/plot_roc_crossval.py format notebook plot_roc_crossval.py #22799
• examples/model_selection/plot_train_error_vs_test_error.py DOC use notebook-style for plot_train_error_vs_test_error #22440
• examples/neighbors/plot_regression.py Update plot_regression.py #22416
• examples/neural_networks/plot_rbm_logistic_classification.py DOC use notebook-style for plot_rbm_logistic_classification.py #23104
• examples/semi_supervised/plot_label_propagation_digits.py Update plot_label_propagation_digits.py #22725
• examples/semi_supervised/plot_label_propagation_structure.py Update plot_label_propagation_structure.py #22726
• examples/svm/plot_rbf_parameters.py Update plot_rbf_parameters.py #22724
• examples/svm/plot_svm_anova.py DOC use notebook-style for plot_svm_anova.py #22779
• examples/svm/plot_svm_regression.py DOC: use notebook-style for plot_svm_regression.py example #22534
• examples/text/plot_document_clustering.py DOC Fix notebook-style for plot_document_clustering.py #22443

end_auto_generated

Suggest a potential alternative/fix

The examples need to be reviewed on a case by case, to know whether they are "notebook-syle", as in https://sphinx-gallery.github.io/stable/tutorials/plot_parse.html#sphx-glr-tutorials-plot-parse-py or not. In general, we should favor notebook-style examples, which are typically more readable.

We should probably favor the "# %%" syntax to the long line of "###"
https://sphinx-gallery.github.io/stable/syntax.html#embed-rst-in-your-example-python-files

In terms of reviewing workflow, it can be useful to to send different PRs, rather than a big PR which will be harder to review.

Pieces of advice if you are interested in working on this issue

• pick a file to get started with: e.g. https://github.com/scikit-learn/scikit-learn/blob/main/examples/semi_supervised/plot_label_propagation_digits.py with its rendered HTML in the doc
• Mention which file you are working in a comment so that different people can work in parallel on different files
• use # %% as cell separator where you think it is appropriate. For example in https://github.com/scikit-learn/scikit-learn/blob/main/examples/semi_supervised/plot_label_propagation_digits.py I would say that some comments may not have their own cell like "Pick the top 10 most uncertain labels" whereas some should be turned into a title like "Plot".
• Look at existing notebook-style example for inspiration e.g. https://github.com/scikit-learn/scikit-learn/blob/main/examples/manifold/plot_swissroll.py with its rendered HTML in the doc
• Look at the contributing doc to build the example HTML locally: https://scikit-learn.org/stable/developers/contributing.html in particular using EXAMPLES_PATTERN=plot_label_propagation_digit make html will only run the examples with plot_label_propagation_digit in their filenames. This makes it quicker to generate the doc for only the example you are working on and look at the HTML rendering locally.
• once you create a PR, check the CircleCI status at the bottom of the page and click on "Details"
  
• It should bring you to a page like this, click on the name of the example you modify and check that the doc for this example looks right:
  

[soma2000-lang]

Working on this

[lesteve]

I have added a list of examples that uses a pattern like # ##### for comments. I think it is best to create one PR by example, this will make it easier to review changes.

[ss-is-master-chief]

@GaelVaroquaux Do you mean that we wish to standardize (# %% (preferred), or # ##) the block splitter across all relevant scripts?

[ss-is-master-chief]

/take

[GaelVaroquaux]

@GaelVaroquaux Do you mean that we wish to standardize (# %% (preferred), or # ##) the block splitter across all relevant scripts?

I believe that "# %%" should be preferred, but I would not do a PR changing this systematically. Rather on a file-by-file basis.

[ss-is-master-chief]

@GaelVaroquaux Make sense! How would you recommend that I help with this?

[lesteve]

@ss-is-master-chief I have added a "Pieces of advice if you are interested in working on this issue" section in the top post to help you (and potentially other interested people to get started). If something is not clear let us know!

[zuggernautt]

I want to help.

[MaxwellLZH]

working on examples/linear_model/plot_lasso_and_elasticnet.py

[Valavanca]

Working on examples/decomposition/plot_faces_decomposition.py

[brendo-k]

Working on examples/model_selection/plot_train_error_vs_test_error.py

[NartayAikyn]

Working on examples/feature_selection/plot_feature_selection.py

[aditya172926]

Working on examples/applications/plot_stock_market.py

[svenstehle]

Working on examples/ensemble/plot_adaboost_hastie_10_2.py

[krishnakoumar27]

Working on examples/cluster/plot_ward_structured_vs_unstructured.py

[danifernandes-hub]

Working on examples/cross_decomposition/plot_compare_cross_decomposition.py

[svenstehle]

Working on examples/ensemble/plot_adaboost_regression.py