Fix notebook-style examples

Describe the issue linked to the documentation

Many legitimate notebook style examples have been broken, and specifically by the following PR https://github.com/scikit-learn/scikit-learn/pull/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

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:

Issue Analytics

State:
Created 2 years ago
Comments:47 (45 by maintainers)

Top GitHub Comments

5reactions

lestevecommented, Feb 8, 2022

@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!

1reaction

lestevecommented, Feb 8, 2022

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.