|
| 1 | +Building the User Tutorials Website Locally |
| 2 | +=========================================== |
| 3 | + |
| 4 | +Here, we provide instructions for setting up an appropriate Python environment and building the SimPEG user tutorials website locally with [MyST](https://mystmd.org/). |
| 5 | + |
| 6 | +## Step 1: Cloning the GitHub Repository |
| 7 | + |
| 8 | +The URL for the SimPEG user tutorials GitHub repository is: https://github.com/simpeg/user-tutorials/. If using the Git Bash shell: |
| 9 | + |
| 10 | +```bash |
| 11 | +git clone https://github.com/simpeg/user-tutorials |
| 12 | +cd user-tutorials |
| 13 | +``` |
| 14 | + |
| 15 | +## Step 2: Setting Up a Python Environment |
| 16 | + |
| 17 | +The Jupyter notebooks containing the tutorials are maintained to run properly using the [latest release of SimPEG](https://github.com/simpeg/simpeg/releases). |
| 18 | +Notebooks may not run correctly if SimPEG is being imported from an earlier release or development branch. |
| 19 | +The [mystmd][install-mystmd] and [nodejs](https://nodejs.org/api/packages.html) are also required to build the website locally. |
| 20 | + |
| 21 | +We advise building a Python environment from the `environment.yml` file in the root directory of the repository. |
| 22 | +To create the `simpeg-user-tutorials` environment using conda: |
| 23 | + |
| 24 | +```bash |
| 25 | +conda env create -f environment.yml |
| 26 | +``` |
| 27 | + |
| 28 | +Once built, you can activate using: |
| 29 | + |
| 30 | +```bash |
| 31 | +conda activate simpeg-user-tutorials |
| 32 | +``` |
| 33 | + |
| 34 | +## Step 3: Build and Execution Commands |
| 35 | + |
| 36 | +The SimPEG user tutorials are a collection of [Jupyter Notebook](https://jupyter.org/) (and [Markdown](https://www.markdownguide.org/getting-started/)) files, |
| 37 | +which [MyST][mystmd.org] builds into a website. Here, we describe the commands that contributors should be familiar with. |
| 38 | + |
| 39 | +:::{important} |
| 40 | +The tutorial notebooks, including their states, are tracked by GitHub. When the SimPEG user tutorials repository was cloned, all notebooks had been run and saved. Therefore, you do not need to rerun all of the notebooks prior to building the website! |
| 41 | +::: |
| 42 | + |
| 43 | +### Locally Build and Serve Website |
| 44 | + |
| 45 | +The following command will build the website and serve it locally. |
| 46 | +This will allow you to preview the website and observe any changes to notebooks on the fly. |
| 47 | +To locally build and serve the website: |
| 48 | +the website: |
| 49 | + |
| 50 | +```bash |
| 51 | +myst start |
| 52 | +``` |
| 53 | + |
| 54 | +Next, follow the instructions prompted by the command to launch the local build in your brower. |
| 55 | + |
| 56 | +### Build Only |
| 57 | + |
| 58 | +The following command will build the website and store the HTML files in |
| 59 | +a new `_build` folder: |
| 60 | + |
| 61 | +```bash |
| 62 | +myst build --html |
| 63 | +``` |
| 64 | + |
| 65 | +### Clean Cached Builds |
| 66 | + |
| 67 | +```bash |
| 68 | +myst clean --all |
| 69 | +``` |
| 70 | + |
| 71 | +### Rerunning Notebooks |
| 72 | + |
| 73 | +When making alterations and rerunning notebooks, we typically do so by launching Jupyter Notebooks: |
| 74 | + |
| 75 | +```bash |
| 76 | +jupyter notebook |
| 77 | +``` |
| 78 | + |
| 79 | +However, we can rerun a notebook and overwrite its output cells in place using `nbconvert`. |
| 80 | +To rerun a single notebook, use: |
| 81 | + |
| 82 | +```bash |
| 83 | +jupyter nbconvert --to notebook --execute --inplace notebook.ipynb |
| 84 | +``` |
| 85 | + |
| 86 | +We may also want to rerun all notebooks in the repository. |
| 87 | +To rerun all notebooks, use: |
| 88 | + |
| 89 | +```bash |
| 90 | +jupyter nbconvert --to notebook --execute --inplace notebooks/**/*.ipynb |
| 91 | +``` |
| 92 | + |
| 93 | +:::{danger} |
| 94 | +Rerunning all notebooks is a computationally intensive task. Some notebooks |
| 95 | +require significant amount of memory to allocate large sensitivity matrices. |
| 96 | +::: |
| 97 | + |
| 98 | +> [!IMPORTANT] |
| 99 | +> If you are using bash as your shell, make sure to run `shopt -s |
| 100 | +> globstar` to enable the `globstar` feature that allows the use of `**` for |
| 101 | +> filename expansion. |
| 102 | +
|
| 103 | + |
| 104 | + |
| 105 | + |
| 106 | +[install-mystmd]: https://mystmd.org/guide/quickstart |
| 107 | +[jupyter]: https://jupyter.org |
| 108 | +[mystmd.org]: https://mystmd.org |
| 109 | + |
0 commit comments