Repository navigation
Add notebook examples to doc site #173
Description
Feature description
Update the doc site to include the notebook examples in their completed state.
Motivation
No response
Possible implementation
I believe this can be completed with nbsphinx.
Additional context
No response
Metadata
Metadata
Assignees
Labels
Type
Projects
- Status
Activity
agriyakhetarpal commentedon Mar 16, 2024
I would rather suggest using
MyST-NB, because it would provide faster documentation builds as the number of notebooks increases, and it looks to be better maintained in comparison, given its more widespread usage across various projects.agriyakhetarpal commentedon Apr 14, 2024
I forgot to mention here, but adding the notebooks to the documentation quickly escalated into several issues – first with parsing regular Markdown content that we have, the rise of many extra docs warnings (some of them coming from
sphinx.autoapi, which should be replaced bysphinx.ext.autodocorsphinx.ext.autosummarywhile PyBOP's source code is still small), a bit with executing the notebooks and getting their outputs saved – with that, the good thing is that their outputs are cached, but we will need to restructure the doc builds and add an additional CI target on PRs (either a matrix or a separate job) and move away fromnox -s notebooks. I also faced some issues with CSS and styling which should be fixable, but all this means is that this seemingly trivial, single task will most likely require a forthcoming plus big documentation overhaul (which I would be happy to do, nonetheless!).I would really not advocate for the other alternative we have, i.e.,
nbsphinx, given that it has many issues and is in maintenance mode rather than adding new features. It would be a step back if this issue's larger goal is to be considered (which is really the accessibility of tutorials and examples for users wanting to try PyBOP). I shall instead advocate for converting/writing notebooks with plain Markdown and updating the existing ones to it with thejupytexttool – doing that will be beneficial for PyBOP in the long run, and can also serve as a pilot for PyBaMM's documentation if it can migrate away from.ipynb-based notebooks in the future. @BradyPlanden and @NicolaCourtier, I would be happy to explain this in more detail in case I am too terse in this description in the next PyBOP developer meeting and make a case for some of these things to see if other core developers would like it, please let me know :) In any case, I think PyBOP being a relatively smaller project would therefore benefit from the lack of inertia that is usually involved with larger projects in comparison.agriyakhetarpal commentedon May 16, 2024
Update from the developer meeting on 16/05/2024, it was agreed that a pilot can be tried for this format for both the hosted documentation and running notebooks in general via JupyterLab. Some tasks that will now be looked into:
BradyPlanden commentedon Aug 2, 2024
Hi @agriyakhetarpal, just following up to see how you're getting on with this. To solve #410, we need to either move away from using Kaleido as a static export backend, or accept lower quality images throughout the notebook in
pngformat. For the former, we would lose the Github rendering of the figures within the notebooks, so to counteract this it would be preferable to have correctly rendered notebooks on the docs.Do you have an example of a markdown based notebook?For reference: https://github.com/mwouts/jupytext/tree/main/demoagriyakhetarpal commentedon Aug 15, 2024
Hi @BradyPlanden – very sorry for the late response on this, I missed the notification on this issue over other notifications that came up above it! I've looked at both #410 and #411, and while I don't have an immediate opinion on this right now, I think it is okay to use PNG notebooks in images for bandwidth reasons, they are much easier to load on webpages. If one wants to extract higher-quality image, they can modify the notebook locally and bump the output resolution anyway. I did put my vote on the timings for the Examples Creation session, so I can revisit my changes (which have now become slightly outdated – maybe I'll refresh by just migrating the notebooks and not mixing the rest of the Sphinx changes in there) and seek feedback.
NicolaCourtier commentedon Jul 14, 2026
This issue might be worth revisiting after #928 which gives us the option to use either matplotlib or plotly for the notebooks. What do you think @agriyakhetarpal ?