Add notebook examples to doc site

[BradyPlanden]

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]

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]

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]

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.