-
-
Notifications
You must be signed in to change notification settings - Fork 454
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
DOC: Add interactive notebooks to pages in the "Usage Examples" section #741
base: main
Are you sure you want to change the base?
DOC: Add interactive notebooks to pages in the "Usage Examples" section #741
Conversation
Quite strange. The documentation is building without any problems locally... Edit: I can reproduce locally if I delete a few of the previously generated files – this is coming from Edit, again: they were failing because the |
8b4fcc8
to
4d1dcf0
Compare
4d1dcf0
to
970439b
Compare
Co-Authored-By: Marc Wouts <marc.wouts@gmail.com>
I added a basic extension to clean up the generated IPython notebooks in 6bc9c60 using |
18b4b2c
to
21e0158
Compare
Processing Markdown programmatically doesn't bear good fruit – it would have been easier if we used IPyNB, and we don't plan to. I would suggest that we should merge this for now, @rgommers. The issue with Markdown was that there isn't a clean way to add both the Jupytext frontmatter and the notebook directives and that requires some obtrusive, prone-to-failure file manipulation by processing the contents as a string (we can keep the notebook directives at the bottom and the frontmatter intact, but it's easier to provide the download buttons at the top of the page rather than at the bottom). |
# nb_execution_allow_errors = True | ||
# nb_execution_show_tb = True |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure what to do with these configuration values, probably best to remove them since both default to True
?
# nb_execution_allow_errors = True | |
# nb_execution_show_tb = True |
Weird, the local docs build and RTD both produce cleaner downloadable notebooks, but the NotebookLite directive on RTD doesn't have the cleaner notebooks (they still have the Sphinx directives). This does not happen locally. I think RTD has some caching troubles, because I removed the redundant module headings from the notebooks (such as Edit: some notebooks are as expected, and some don't. Edit 2: this is most likely the case of a cached build or some updates that don't trickle down the RTD, the logs say that all the notebooks are converted. I can't reproduce locally, and I feel that the issue will go away automatically on a fresh build. |
I had a revelation just now and I think 07a0926 should fix the synchronisation issue for good – the RTD build is just buggy for some reason or the other and the local documentation builds where the issue doesn't arise can be trusted upon. Ready for review and further proceedings. |
Description
Tip
Those interested can try it at https://pywavelets--741.org.readthedocs.build/en/741/regression/index.html
The Usage Examples section, following #728 and as requested in #737 (comment), is rendered interactive through the changes in this PR through the use of
jupyterlite-sphinx
and Markdown-based notebooks that are executed by MyST-NB. Please read below for a granular overview of all of these details:Which issue does this PR solve/reference?
Addresses a part of #706
Key changes made
.rst
based files underdoc/source/regression
converted to Markdown and reformatted as notebooksconf.py
jupyterlite-sphinx
to run the notebooks under WASM in the same tab (and something like Add the option to open JupyterLite window in new tab jupyterlite/jupyterlite-sphinx#165 can be added for this directive as well).ipynb
-based notebooks that get generated during the process in order to keep the documentation build warning-free. Generating them at build time is for theNotebookLite
directive to be able to access them and load them, since the NotebookLite directive currently does not load.md
files or notebook files in other formats.i. I imagine this will be helpful for DOC: stats: Convert sampling tutorial to MyST-md scipy/scipy#20303 as well where it is required to load the notebooks in an interactive manner under a specific folder. The notebooks are not executed by Jupytext at the time of conversion, and therefore, based on past experiments, it takes ~10 seconds to convert 30 or so notebooks.
Additional context
This is just a pilot run of how notebook-based examples can be configured for Sphinx-based documentation websites, so there are a few corner cases that I have noticed so far:
conf.py
just like how theTryExamples
directive can be configured.A brief to-do list
Besides the points mentioned above, smaller tasks can be looked into:
.md
and.ipynb
)