Building the User Tutorials Website Locally

Here, we provide instructions for setting up an appropriate Python environment and building the SimPEG user tutorials website locally with MyST.

Step 1: Cloning the GitHub Repository¶

The URL for the SimPEG user tutorials GitHub repository is: https://github.com/simpeg/user-tutorials/. If using the Git Bash shell:

git clone https://github.com/simpeg/user-tutorials
cd user-tutorials

Step 2: Setting Up a Python Environment¶

The Jupyter notebooks containing the tutorials are maintained to run properly using the latest release of SimPEG. Notebooks may not run correctly if SimPEG is being imported from an earlier release or development branch. The mystmd and nodejs are also required to build the website locally.

We advise building a Python environment from the environment.yml file in the root directory of the repository. To create the simpeg-user-tutorials environment using conda:

conda env create -f environment.yml

Once built, you can activate using:

conda activate simpeg-user-tutorials

Step 3: Build and Execution Commands¶

The SimPEG user tutorials are a collection of Jupyter Notebook (and Markdown) files, which MyST builds into a website. Here, we describe the commands that contributors should be familiar with.

Locally Build and Serve Website¶

The following command will build the website and serve it locally. This will allow you to preview the website and observe any changes to notebooks on the fly. To locally build and serve the website: the website:

myst start

Next, follow the instructions prompted by the command to launch the local build in your brower.

Build Only¶

The following command will build the website and store the HTML files in a new _build folder:

myst build --html

Clean Cached Builds¶

myst clean --all

Rerunning Notebooks¶

When making alterations and rerunning notebooks, we typically do so by launching Jupyter Notebooks:

jupyter notebook

However, we can rerun a notebook and overwrite its output cells in place using nbconvert. To rerun a single notebook, use:

jupyter nbconvert --to notebook --execute --inplace notebook.ipynb

We may also want to rerun all notebooks in the repository. To rerun all notebooks, use:

jupyter nbconvert --to notebook --execute --inplace notebooks/**/*.ipynb