Fix notebook-style examples #22406
Assignees
Labels
Documentation
Easy
Well-defined and straightforward way to resolve
good first issue
Easy with clear instructions to resolve
Comments
|
Working on this |
|
I have added a list of examples that uses a pattern like |
|
@GaelVaroquaux Do you mean that we wish to standardize ( |
|
/take |
|
@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.
|
|
@GaelVaroquaux Make sense! How would you recommend that I help with this? |
|
@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! |
|
I want to help. |
1 task
|
Working on examples/applications/plot_stock_market.py |
Repository owner
moved this from Issues that are list of sub-issues
to Done
in WiMLDS Paris Sprint
May 13, 2022
This was referenced Jun 21, 2022
This was referenced Nov 3, 2022
This was referenced Nov 14, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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 byag -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
# %%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".EXAMPLES_PATTERN=plot_label_propagation_digit make htmlwill only run the examples withplot_label_propagation_digitin 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.The text was updated successfully, but these errors were encountered: