refactor docs from jupyter-execute to myst-nb

Author: JoelLucaAdams

docs/_static/jupyter_padding.css

@@ -1,10 +1,16 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
+
 # Animations
 
 [`xarray.DataArray.epoch.animate`](project:#sdf_xarray.plotting.animate)
 creates a <inv:#matplotlib.animation.FuncAnimation>; it is designed to
 mimic <inv:#xarray.DataArray.plot>.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 import sdf_xarray as sdfxr
 import xarray as xr
 import matplotlib.pyplot as plt
@@ -22,15 +28,12 @@ The type of plot that is animated is determined by the dimensionality of the
 resolved data has 2 dimensions.
 ```
 
-```{csv-table}
-:header: >
-:    "Dimensions", "Plotting function", "Notes"
-:widths: "auto"
+| Dimensions |      Plotting function        |        Notes          |
+| ---------- | ----------------------------- | --------------------- |
+|    `2`     | <inv:#xarray.plot.line>       |                       |
+|    `3`     | <inv:#xarray.plot.pcolormesh> |                       |
+|    `>3`    | <inv:#xarray.plot.hist>       | Not fully implemented |
 
-`2`, <inv:#xarray.plot.line>, ""
-`3`, <inv:#xarray.plot.pcolormesh>, ""
-`>3`, <inv:#xarray.plot.hist>, "Not fully implemented"
-```
 
 ### 1D simulation
 
@@ -42,7 +45,7 @@ It is important to note that since the dataset is time resolved, it has
 `anim.show()` will only show the animation in a Jupyter notebook.
 ```
 
-```{jupyter-execute}
+```{code-cell} ipython3
 # Open the SDF files
 ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
@@ -76,7 +79,7 @@ plt.show()
 
 Plotting a 2D simulation can be done in exactly the same way.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
 da = ds["Derived_Number_Density_Electron"]
 anim = da.epoch.animate()
@@ -86,7 +89,7 @@ anim.show()
 We can also take a lineout of a 2D simulation to create 2D data and
 plot it as a <inv:#xarray.plot.line>.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 da = ds["Derived_Number_Density_Electron"]
 da_lineout = da.sel(Y_Grid_mid = 1e-6, method = "nearest")
 anim = da_lineout.epoch.animate(title = "Y = 1e-6 [m]")
@@ -100,7 +103,7 @@ return a <inv:#xarray.plot.hist>. However, this may not be
 desirable. We can plot a 3D simulation along a certain plane in the
 same way a 2D simulation can be plotted along a line.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = sdfxr.open_mfdataset("tutorial_dataset_3d/*.sdf")
 
 da = ds["Derived_Number_Density"]
@@ -112,7 +115,7 @@ anim.show()
 A single SDF file can be animated by changing the time coordinate of
 the animation.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = sdfxr.open_dataset("tutorial_dataset_3d/0005.sdf")
 da = ds["Derived_Number_Density"]
 anim = da.epoch.animate(t = "X_Grid_mid")
@@ -130,7 +133,7 @@ EPOCH allows for simulations that have a moving simulation window
 You must use <inv:#xarray.open_mfdataset> and specify arguments in the following way.
 ```
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = xr.open_mfdataset(
    "tutorial_dataset_2d_moving_window/*.sdf",
    preprocess = sdfxr.SDFPreprocess(),
@@ -158,7 +161,7 @@ see [`xarray.DataArray.epoch.animate`](project:#sdf_xarray.plotting.animate) for
 The coordinate units can be converted before plotting as in [](./unit_conversion.md#unit-conversion).
 Some functionality such as `aspect` and `size` are not fully implemented yet.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
 
 # Change the units of the coordinates
@@ -191,7 +194,7 @@ that contains multiple plots layered on top of each other.
 What follows is an example of how to combine multiple animations on the
 same axis.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
 anim = ds.epoch.animate_multiple(
@@ -214,7 +217,7 @@ the `alpha` value which sets the opacity of the plot.
 
 This also works with 2 dimensional data.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 import numpy as np
 from matplotlib.colors import LogNorm
 

docs/animation.md

@@ -47,13 +47,13 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_autodoc_typehints",
-    "myst_parser",
-    "jupyter_sphinx",
+    "myst_nb",
     "sphinx_copybutton",
     "sphinx_togglebutton",
 ]
 
-source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+source_suffix = {".rst": "restructuredtext", ".md": "myst-nb"}
+
 myst_heading_anchors = 3
 
 autosummary_generate = True
@@ -106,7 +106,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_css_files = ["force_render_dark_xarray_objects.css", "jupyter_padding.css"]
+html_css_files = ["force_render_dark_xarray_objects.css"]
 
 html_theme_options = {
     "repository_url": "https://github.com/epochpic/sdf-xarray",

docs/conf.py

@@ -1,6 +1,12 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
+
 # Key Functionality
 
-```{jupyter-execute}
+```{code-cell} ipython3
 import xarray as xr
 import sdf_xarray as sdfxr
 import matplotlib.pyplot as plt
@@ -10,15 +16,15 @@ import matplotlib.pyplot as plt
 
 ### Loading single files
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf")
 ```
 
 You can also load the data in as a <inv:#xarray.DataTree>, which organises the data
 hierarchically into `groups` (for example grouping related quantities such as the individual
 components of the electric and magnetic fields) while keeping each item as a <inv:#xarray.Dataset>.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_datatree("tutorial_dataset_1d/0010.sdf")
 ```
 
@@ -29,7 +35,7 @@ sdfxr.open_datatree("tutorial_dataset_1d/0010.sdf")
 If you wish to load data directly from the `SDF.C` library and ignore
 the <inv:#xarray> interface layer.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 raw_ds = sdfxr.SDFFile("tutorial_dataset_1d/0010.sdf")
 raw_ds.variables.keys()
 ```
@@ -46,7 +52,7 @@ to a nan value. To remove these nan values we suggest using the <inv:#xarray.Dat
 function or following our implmentation in [](#loading-sparse-data).
 ```
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 ```
 
@@ -55,7 +61,7 @@ all the files we have do some processing of the data so that we can correctly al
 the time dimension; This is done via the `preprocess` parameter utilising the
 <project:#sdf_xarray.SDFPreprocess> function.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 xr.open_mfdataset(
    "tutorial_dataset_1d/*.sdf",
    join="outer",
@@ -68,7 +74,7 @@ You can also load the data in as a <inv:#xarray.DataTree>, which organises the d
 hierarchically into `groups` (for example grouping related quantities such as the individual
 components of the electric and magnetic fields) while keeping each item as a <inv:#xarray.Dataset>.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
 ```
 
@@ -82,7 +88,7 @@ need for a single, large time dimension that would be filled with nan values. Th
 significantly reduces memory consumption, though it requires more deliberate handling
 if you need to compare variables that exist on these different time coordinates.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf", separate_times=True)
 ```
 
@@ -109,7 +115,7 @@ Pass `keep_particles=True` as a keyword argument to
 <inv:#xarray.open_dataset> (for single files) or <inv:#xarray.open_mfdataset> (for
 multiple files).
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf", keep_particles=True)
 ```
 
@@ -125,7 +131,7 @@ variables. This creates a dataset consisting only of the given variable(s)
 and the relevant coordinates/dimensions, significantly reducing memory
 consumption.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf", data_vars=["Electric_Field_Ex"])
 ```
 
@@ -154,8 +160,9 @@ There are a few ways you can load an input deck:
 
 An example of loading a deck can be seen below
 
-````{toggle}
-```{jupyter-execute}
+```{code-cell} ipython3
+:tags: [hide-output]
+
 import json
 from IPython.display import Code
 
@@ -167,7 +174,6 @@ deck = ds.attrs["deck"]
 json_str = json.dumps(deck, indent=4)
 Code(json_str, language='json')
 ```
-````
 
 ## Data interaction examples
 
@@ -185,7 +191,7 @@ It is important to note here that <inv:#xarray> lazily loads the data
 meaning that it only explicitly loads the results your currently
 looking at when you call `.values`
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
 ds["Electric_Field_Ex"]
@@ -197,7 +203,7 @@ using the built-in <inv:#xarray.DataArray.plot> function (see
 a simple call to `matplotlib`. This also means that you can access
 all the methods from `matplotlib` to manipulate your plot.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 # This is discretized in both space and time
 ds["Electric_Field_Ex"].plot()
 plt.title("Electric field along the x-axis")
@@ -210,7 +216,7 @@ This dimension represents all the recorded simulation steps and allows
 for easy indexing. To quickly determine the number of time steps available,
 you can check the size of the time dimension.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 # This corresponds to the number of individual SDF files loaded
 print(f"There are a total of {ds['time'].size} time steps")
 
@@ -224,7 +230,7 @@ index of the time step with the <inv:#xarray.Dataset.isel> function. This can be
 done by passsing the index to the `time` parameter (e.g., `time=0` for
 the first snapshot).
 
-```{jupyter-execute}
+```{code-cell} ipython3
 # We can plot the variable at a given time index
 ds["Electric_Field_Ex"].isel(time=20)
 ```
@@ -237,7 +243,7 @@ If you know roughly what time you wish to select but not the exact value
 you can use the parameter `method="nearest"`.
 ```
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds["Electric_Field_Ex"].sel(time=sim_time)
 ```
 
@@ -280,7 +286,7 @@ Below is an example gif of how this interfacing looks as seen on
 These datasets can also be easily manipulated the same way as you
 would with `numpy` arrays.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds["Laser_Absorption_Fraction_in_Simulation"] = (
    (ds["Total_Particle_Energy_in_Simulation"] - ds["Total_Particle_Energy_in_Simulation"][0])
    / ds["Absorption_Total_Laser_Energy_Injected"]
@@ -298,15 +304,15 @@ plt.show()
 You can also call the `plot()` function on several variables with
 labels by delaying the call to `plt.show()`.
 
-```{jupyter-execute}
+```{code-cell} ipython3
 ds["Total_Particle_Energy_Electron"].plot(label="Electron")
 ds["Total_Particle_Energy_Ion"].plot(label="Ion")
 plt.title("Particle Energy in Simulation per Species")
 plt.legend()
 plt.show()
 ```
 
-```{jupyter-execute}
+```{code-cell} ipython3
 print(f"Total laser energy injected: {ds["Absorption_Total_Laser_Energy_Injected"][-1].values:.1e} J")
 print(f"Total particle energy absorbed: {ds["Total_Particle_Energy_in_Simulation"][-1].values:.1e} J")
 print(f"The laser absorption fraction: {ds["Laser_Absorption_Fraction_in_Simulation"][-1].values:.1f} %")