search

pybop-team / PyBOP

A parameterisation and optimisation package for battery models.
https://pybop-docs.readthedocs.io
BSD 3-Clause "New" or "Revised" License
66 stars 20 forks source link

Add notebook examples to doc site #173

Open BradyPlanden opened 9 months ago

BradyPlanden commented 9 months ago

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

agriyakhetarpal commented 7 months ago

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 commented 6 months ago

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 by sphinx.ext.autodoc or sphinx.ext.autosummary while 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 from nox -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 the jupytext tool – 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 commented 5 months ago

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:

  1. can be tried with a few notebooks first so that people can see how they like Markdown-based notebooks and how to fit in with that ecosystem,
  2. investigate pairing of notebooks with Jupytext, and
  3. add documentation on usage plus contributing guides so that the transition for readers and core developers is smooth and accessible at the same time.
BradyPlanden commented 3 months ago

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 png format. 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/demo

agriyakhetarpal commented 2 months ago

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.