From dae4eed4340c0ac56fce0185e92c6e658d418a7e Mon Sep 17 00:00:00 2001 From: dccowan Date: Wed, 11 Dec 2024 10:23:57 -0800 Subject: [PATCH 1/8] New PR template added --- .github/pull_request_template.md | 46 ++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..26b2b71 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,46 @@ + + +#### Summary + + +#### PR Checklist +* [ ] If this is a work in progress PR, set as a Draft PR +* [ ] Introduction is complete: + * [ ] Author has been added to notebook + * [ ] An introductory paragraph summarizing the notebook's contents has been added + * [ ] Appropriate admonitions for notebook difficulty and computational resources have been added + * [ ] Appropriate keywords have been added + * [ ] Learning objectives have been listed + * [ ] Hyperlinks to other tutorial notebooks and important classes/functionality have been added +* [ ] Each section is properly formatted + * [ ] Short summary of what is being done + * [ ] Newly introduced functionality is explained or a link is provided to a relevant notebook + * [ ] Links to API documentation added for all classes and functionality + * [ ] Data, models, etc... are plotted whenever possible +* [ ] Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). +* [ ] Added [tests](https://docs.simpeg.xyz/latest/content/getting_started/contributing/testing.html) to verify changes to the code. +* [ ] Marked as ready for review (if this is was a draft PR), and converted + to a Pull Request +* [ ] Tagged ``@simpeg/simpeg-developers`` when ready for review. + + +#### Additional information + + + + From 153ab742f12521296a95676a916ce4437b18f2dc Mon Sep 17 00:00:00 2001 From: dccowan Date: Thu, 12 Dec 2024 15:17:45 -0800 Subject: [PATCH 2/8] preliminary contributors instructions --- myst.yml | 5 + .../fwd_gravity_gradiometry_3d.ipynb | 2 +- notebooks/contributing_index.md | 32 +++ notebooks/generating_pr.md | 21 ++ notebooks/getting_started.md | 135 ++++++++++++ notebooks/notebook_formatting.md | 192 ++++++++++++++++++ 6 files changed, 386 insertions(+), 1 deletion(-) create mode 100644 notebooks/contributing_index.md create mode 100644 notebooks/generating_pr.md create mode 100644 notebooks/getting_started.md create mode 100644 notebooks/notebook_formatting.md diff --git a/myst.yml b/myst.yml index 9db9d49..e2e081b 100644 --- a/myst.yml +++ b/myst.yml @@ -115,6 +115,11 @@ project: children: - file: notebooks/12-pgi-inversion/plot_inv_1_joint_pf_pgi_full_info_tutorial.ipynb - file: notebooks/12-pgi-inversion/plot_inv_2_joint_pf_pgi_no_info_tutorial.ipynb + - file: notebooks/contributing_index.md + children: + - file: notebooks/getting_started.md + - file: notebooks/notebook_formatting.md + - file: notebooks/generating_pr.md site: template: book-theme diff --git a/notebooks/03-gravity/fwd_gravity_gradiometry_3d.ipynb b/notebooks/03-gravity/fwd_gravity_gradiometry_3d.ipynb index d9460f6..54c7a46 100644 --- a/notebooks/03-gravity/fwd_gravity_gradiometry_3d.ipynb +++ b/notebooks/03-gravity/fwd_gravity_gradiometry_3d.ipynb @@ -782,7 +782,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.15" + "version": "3.10.16" } }, "nbformat": 4, diff --git a/notebooks/contributing_index.md b/notebooks/contributing_index.md new file mode 100644 index 0000000..d0d49ad --- /dev/null +++ b/notebooks/contributing_index.md @@ -0,0 +1,32 @@ +Contributing to User-Tutorials +============================== + +User tutorials have become the primary resource for SimPEG users to learn the code base and best-practices for computational geophysics. +To ensure a high level of consistency and quality, specific guidelines need to be followed when adding new tutorial notebooks. +New tutorial notebooks will not be published until our guidelines have been followed. + +Before You Create a Tutorial +---------------------------- + +Although we greatly appreciate efforts by the SimPEG community to create new tutorials, +we must ensure the contents of the tutorial are appropriate. As a result, +we discourage tutorials that fall into the following categories: + +* the tutorial focusses on functionality that is not part of SimPEG +* the amount of SimPEG functionality that has not already been covered in another tutorial is insufficient +* the tutorial focusses on a data-specific result and is not generalizable +* the tutorial was created for purpose of self promotion + + +How to Contribute +----------------- + +To add a new notebook to SimPEG user tutorials, you will need to complete the following three steps: + +1. Follow the instructions on the [Cloning the Repository and Building the Website](getting_started.md) page. +These instructions explain how to clone the SimPEG user tutorials repository, setup the appropriate Python +environment, and build the website locally with MyST. + +2. Create a notebook according to the [Structure and Formatting for Notebooks](notebook_formatting.md) page. + +3. Create a GitHub pull request. \ No newline at end of file diff --git a/notebooks/generating_pr.md b/notebooks/generating_pr.md new file mode 100644 index 0000000..ab6d100 --- /dev/null +++ b/notebooks/generating_pr.md @@ -0,0 +1,21 @@ +GitHub Pull Request and Review +============================== + +Requirements Checklist +---------------------- + +The following is a useful checklist for determining whether a new tutorial notebook follows our guidelines: + +* **The introduction is complete:** + * Title and author added to notebook + * Admonitions for notebook difficulty and computational resources have been added + * Keywords list has been added + * Summary paragraph describing the tutorial has been added + * Learning objectives have been listed + * Hyperlinks to other tutorial notebooks added if necessary +* **For each section:** + * Short summary of what is being done + * Newly introduced functionality is explained or a link is provided to a relevant notebook + * Links to API documentation added for all classes and functions that are used + * Data, models, etc... are plotted appropriately + * Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). \ No newline at end of file diff --git a/notebooks/getting_started.md b/notebooks/getting_started.md new file mode 100644 index 0000000..9d997d7 --- /dev/null +++ b/notebooks/getting_started.md @@ -0,0 +1,135 @@ +Cloning the Repository and Building the Website Locally +======================================================= + +## Cloning the GitHub Repository + +The GitHub repository for SimPEG User Tutorials can cloned from https://github.com/simpeg/user-tutorials/. +If using the Git Bash shell: + +```bash +git clone https://github.com/simpeg/user-tutorials +cd user-tutorials +``` + +## Setting Up Your Python Environment + +The notebooks are maintained so that they run correctly using the latest SimPEG release. Some notebooks may not +run correctly if SimPEG is being imported from an earlier release or development branch. The website is built +from the collection of Markdown files and Jupyter notebooks using [Myst][mystmd.org]. To build the website locally, +you will need to [install `mystmd`][install-mystmd] + +For contributors, an `environment.yml` file has been provided in the root directory of the repository. +To create the environment using conda: + +```bash +conda env create -f environment.yml +``` + +## How to build the website locally + +The SimPEG User Tutorials were created using [Myst][mystmd.org]. Myst is +capable of building the website from content stored in [Jupyter +Notebooks][jupyter]. + +We can build the website from the current content in the Jupyter Notebooks. +This can be done in a few seconds with very slim resource requirements. + +Rerunning the notebooks is a more intensive task that will require significant +amount of memory (specially for the computationally intensive notebooks) and it +will take some time. + +Here you'll find instructions to: + +- [Build and the website locally](#build-and-serve-the-website-locally) +- [Rerun notebooks in the repo](#rerun-notebooks) + +### Build and Serve the Website Locally + +#### Build and Serve + +The following command will build the website and serve it locally, so you can +preview it. Follow the instructions that will be prompted by the command to see +the website: + +```bash +msyt start +``` + +#### Build Only + +The following command will build the website and store the HTML files in +a new `_build` folder: + +```bash +msyt build --html +``` + +#### Clean Cached Builds + +```bash +myst clean --all +``` + +### Rerun Notebooks + +Start by cloning this repository: + +```bash +git clone https://github.com/simpeg/user-tutorials +cd user-tutorials +``` + +And create a `conda` environment using the provided `environment.yml` file: + +```bash +conda env create -f environment.yml +``` + +We can use `nbconvert` to rerun a notebook and overwrite its output cells +in place. +To rerun a single notebook, use: + +```bash +jupyter nbconvert --to notebook --execute --inplace notebook.ipynb +``` + +To rerun all notebooks, use: + +> [!CAUTION] +> Rerunning all notebooks is a computationally intensive task. Some notebooks +> require significant amount of memory to allocate large sensitivity matrices. + +> [!IMPORTANT] +> If you are using bash as your shell, make sure to run `shopt -s +> globstar` to enable the `globstar` feature that allows the use of `**` for +> filename expansion. + +```bash +jupyter nbconvert --to notebook --execute --inplace notebooks/**/*.ipynb +``` + + +[install-mystmd]: https://mystmd.org/guide/quickstart +[jupyter]: https://jupyter.org +[mystmd.org]: https://mystmd.org + + +## Check Style of Notebooks + +We can check the code style of our notebooks using [`ruff`][ruff] and +[`nbqa`][nbqa]. Simply run the following command to check the style of the +notebooks: + +```bash +nbqa ruff notebooks +``` + +And run this to autoformat them: + +```bash +nbqa ruff --fix notebooks +``` + +Alternatively, you can use the targets we have in the `Makefile`, like `make +check` and `make format`. Read more information about the available targets +by running `make help`. \ No newline at end of file diff --git a/notebooks/notebook_formatting.md b/notebooks/notebook_formatting.md new file mode 100644 index 0000000..d157deb --- /dev/null +++ b/notebooks/notebook_formatting.md @@ -0,0 +1,192 @@ +Structure and Formatting for Notebooks +====================================== + +For consistency, tutorial notebooks follow strict structure and formatting requirements. Each notebook begins with an introductory section, comprised of several Markdown cells. The contents of the notebook are parsed into sections. Each section contains a Markdown cells, code cells, and plot outputs. For example, see the [3D integral formulation](xref:simpeg#simpeg.potential_fields.gravity.Simulation3DIntegral) tutorial. The structure and formatting requirements for tutorial notebooks are discussed below. + +### Introduction Markdown + +Every tutorial notebook must provide a thorough introduction. + +#### Cell 1: Title Cell + +The first cell in the notebooks is a Markdown cell containing the title and the author for the tutorial. It is formatted as follows. +The title is in quotations. You will need to add yourself as an author in the `myst.yml` file in the root directory of the repository. + +``` +--- +title: "My Notebook Title In Quotes" +authors: + - id: devincowan +--- +``` + +#### Cell 2: Tutorial Difficulty + +Here, we indicate whether the notebook contains introductory, intermediate or advanced content. The author is required to choose +from one of the following [MyST admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html), which is rendered when the webpage is built. + +``` +:::{admonition} Introductory notebook +:class: hint +This tutorial teaches basic functionality within SimPEG and is a good +entry point for new users. +::: +``` + +``` +:::{admonition} Intermediate notebook +:class: caution +This tutorial focusses on intermediate level functionality within SimPEG. +Basic functionality within SimPEG is not discussed in detail, as we assume +the user is already familiar. +::: +``` + +``` +:::{admonition} Advanced notebook +:class: danger +This tutorial focusses on advanced functionality within SimPEG. Basic and +intermediate level functionality are not discussed in detail, as we assume +the user is already an experienced SimPEG user. +::: +``` + +#### Cell 3: Computational Requirements + +Here, we specify the computational requirements to run the notebook. Whereas some notebooks can be run easily on laptop computers, some notebook may need to be exported as Python files and run using cluster computing. The author is required to choose from one of the following [MyST admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html), which is rendered when the webpage is built. + +``` +:::{admonition} Light-weight notebook +:class: hint +This tutorial requires minimal computational resources and can be executed +quickly in the background while other computer processes are running. +::: +``` + +``` +:::{admonition} Medium-weight notebook +:class: caution +Requires moderate computational resources. Run-times may exceed several +minutes and require up to 8 GB of available RAM. +::: +``` + +``` +:::{admonition} Computationally intensive notebook +:class: danger +The computational resources required to execute this notebook exceed those +provided by standard laptop computers. To execute the notebook, please deploy +to a cluster computing environment. +::: +``` + +#### Cell 4: Keywords, Summary and Learning Objectives + +In this cell, please provide keywords relevant to the notebook. E.g. + +``` +**Keywords:** gravity inversion, sparse-norm inversion, integral formulation, tree mesh. +``` + +Next, summarize the purpose of the tutorial. The summary should be roughly one paragraph. If your tutorial focusses on particular functionality within SimPEG, please link to the API documentation. Please link to tutorials you feel the reader should have already worked through. E.g. + +``` +**Summary:** Here we invert gravity anomaly data to recover a density contrast model. +We demonstrate two approaches for recovering a density contrast model: + +1. Weighted least-squares inversion for a tensor mesh +2. Iteratively re-weighted least-squares (IRLS) inversion for a tree mesh + +The *weighted least-squares* approach is a great introduction to geophysical inversion +with SimPEG. One drawback however, is that it recovers smooth structures which may not +be representative of the true model. To recover sparse and/or blocky structures, we +also demonstrate the *iteratively re-weighted least-squares* approach. Because this +tutorial focusses primarily on inversion-related functionality, we urge the reader to +become familiar with functionality explained in the [3D Forward Simulation of Gravity +Anomaly Data](fwd_gravity_anomaly_3d.ipynb) tutorial before working through this one. +``` + +Finally, provide learning objectives as a bullet list. E.g. + +``` +**Learning Objectives:** + +- How geophysical inversion is carried out using SimPEG. +- How to assign appropriate uncertainties to gravity anomaly data. +- How to design a suitable mesh for gravity inversion when using the integral formulation. +- How to choose and set parameters for the inversion. +- How to define directives that are applied and updated throughout the inversion. +- How to applying the sensitivity weighting generally used in 3D gravity inversion. +- How to invert data using weighted least-squares and sparse-norm regularization. +- How to analyse inversion results. +``` + +### Formatting Tutorial Sections + +Each section (or subsection) is constructed using a combination of Markdown and code cells. The structure and formatting of these are discussed below. + +#### Section Header and Summary Cell + +Each section (or subsection) begins with a Markdown cell containing the section header and a summary. +Here, the author must: + +* summarize what is being done in the section +* describe any new functionality that is being introduced +* provide links to all relevant API documentation +* describe the choices for hyperparameter values used in the tutorial. + +E.g. +``` +## Define the Survey + +Surveys within SimPEG generally require the user to create and connect three +types of objects: + +- [receivers](xref:simpeg#simpeg.potential_fields.gravity.receivers.Point): +which define the locations of field measurements and type of data being measured. +- [sources](xref:simpeg#simpeg.potential_fields.gravity.sources.SourceField): +the passive or active sources responsible for generating geophysical responses, +and their associated receivers. +- [survey](xref:simpeg#simpeg.potential_fields.gravity.survey.Survey): the object +which stores and organizes all of the sources and receivers. + +Here, we define the survey that will be used for the forward simulation. Gravity +surveys are simple to create. The user only needs an (N, 3) +[numpy.ndarray](xref:numpy#numpy.ndarray) to define the xyz locations of the +observation locations, and a list of field components +which are to be measured. For the tutorial simulation, the receivers are located +5 m above the surface topography and spaced 10 m apart. +``` + +#### Code Block Cells: + +Code blocks must follow the [style required by SimPEG](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). +Please provide comments when defining new objects. This is especially important when exposing the reader to new functionality. + +E.g. + +``` +# Define the component(s) of the field we want to simulate as strings within +# a list. Here we simulate only the vertical component of the gravity anomaly. +components = ["gz"] + +# Use the observation locations and components to define receivers for the entire survey +# in one step. The set of receivers, even if it's only 1, are organized within a list. +receiver_list = gravity.receivers.Point(receiver_locations, components=components) +receiver_list = [receiver_list] + +# Defining the source. For gravity surveys, we simply need to specific the list of +# receivers associated with the source field. +source_field = gravity.sources.SourceField(receiver_list=receiver_list) + +# Defining the survey. +survey = gravity.survey.Survey(source_field) +``` + +#### Comments on Plotting: + +The author is required to plot data, models, etc... When generating plot, please ensure: + +* the figure renders at an appropriate size for display +* the code used to generate the plot is compact +* text and features within the plot are legible \ No newline at end of file From 6b84e76d9455d7697df3e0cc6f0ff7e1fae5ff3c Mon Sep 17 00:00:00 2001 From: dccowan Date: Fri, 13 Dec 2024 11:11:30 -0800 Subject: [PATCH 3/8] edits to contributors pages --- index.md | 7 + myst.yml | 6 +- notebooks/contributing/build_website.md | 109 ++++++++++++++ .../formatting.md} | 142 +++++++++++++++--- .../pull_request.md} | 4 +- notebooks/contributing_index.md | 46 +++--- notebooks/getting_started.md | 135 ----------------- 7 files changed, 266 insertions(+), 183 deletions(-) create mode 100644 notebooks/contributing/build_website.md rename notebooks/{notebook_formatting.md => contributing/formatting.md} (55%) rename notebooks/{generating_pr.md => contributing/pull_request.md} (92%) delete mode 100644 notebooks/getting_started.md diff --git a/index.md b/index.md index 9c9c17c..bc27217 100644 --- a/index.md +++ b/index.md @@ -106,3 +106,10 @@ Requires moderate computational resources. Run-times may exceed several minutes The computational resources required to execute this notebook exceed those provided by standard laptop computers. To execute the notebook, please deploy to a cluster computing environment. ``` +Want to Add a Tutorial? +----------------------- + +Please visit the [Contributing to User Tutorials](notebooks/contributing_index.md) page to find out how you can add a tutorial. + + + diff --git a/myst.yml b/myst.yml index e2e081b..affeec0 100644 --- a/myst.yml +++ b/myst.yml @@ -117,9 +117,9 @@ project: - file: notebooks/12-pgi-inversion/plot_inv_2_joint_pf_pgi_no_info_tutorial.ipynb - file: notebooks/contributing_index.md children: - - file: notebooks/getting_started.md - - file: notebooks/notebook_formatting.md - - file: notebooks/generating_pr.md + - file: notebooks/contributing/build_website.md + - file: notebooks/contributing/formatting.md + - file: notebooks/contributing/pull_request.md site: template: book-theme diff --git a/notebooks/contributing/build_website.md b/notebooks/contributing/build_website.md new file mode 100644 index 0000000..b55e146 --- /dev/null +++ b/notebooks/contributing/build_website.md @@ -0,0 +1,109 @@ +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](https://mystmd.org/). + +## 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: + +```bash +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](https://github.com/simpeg/simpeg/releases). +Notebooks may not run correctly if SimPEG is being imported from an earlier release or development branch. +The [mystmd][install-mystmd] and [nodejs](https://nodejs.org/api/packages.html) 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: + +```bash +conda env create -f environment.yml +``` + +Once built, you can activate using: + +```bash +conda activate simpeg-user-tutorials +``` + +## Step 3: Build and Execution Commands + +The SimPEG user tutorials are a collection of [Jupyter Notebook](https://jupyter.org/) (and [Markdown](https://www.markdownguide.org/getting-started/)) files, +which [MyST][mystmd.org] builds into a website. Here, we describe the commands that contributors should be familiar with. + +:::{important} +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! +::: + +### 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: + +```bash +msyt 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: + +```bash +msyt build --html +``` + +### Clean Cached Builds + +```bash +myst clean --all +``` + +### Rerunning Notebooks + +When making alterations and rerunning notebooks, we typically do so by launching Jupyter Notebooks: + +```bash +jupyter notebook +``` + +However, we can rerun a notebook and overwrite its output cells in place using `nbconvert`. +To rerun a single notebook, use: + +```bash +jupyter nbconvert --to notebook --execute --inplace notebook.ipynb +``` + +We may also want to rerun all notebooks in the repository. +To rerun all notebooks, use: + +```bash +jupyter nbconvert --to notebook --execute --inplace notebooks/**/*.ipynb +``` + +:::{danger} +Rerunning all notebooks is a computationally intensive task. Some notebooks +require significant amount of memory to allocate large sensitivity matrices. +::: + +> [!IMPORTANT] +> If you are using bash as your shell, make sure to run `shopt -s +> globstar` to enable the `globstar` feature that allows the use of `**` for +> filename expansion. + + + + +[install-mystmd]: https://mystmd.org/guide/quickstart +[jupyter]: https://jupyter.org +[mystmd.org]: https://mystmd.org + diff --git a/notebooks/notebook_formatting.md b/notebooks/contributing/formatting.md similarity index 55% rename from notebooks/notebook_formatting.md rename to notebooks/contributing/formatting.md index d157deb..eb0cd67 100644 --- a/notebooks/notebook_formatting.md +++ b/notebooks/contributing/formatting.md @@ -1,15 +1,22 @@ -Structure and Formatting for Notebooks -====================================== +Tutorial Structure and Formatting Requirements +============================================== -For consistency, tutorial notebooks follow strict structure and formatting requirements. Each notebook begins with an introductory section, comprised of several Markdown cells. The contents of the notebook are parsed into sections. Each section contains a Markdown cells, code cells, and plot outputs. For example, see the [3D integral formulation](xref:simpeg#simpeg.potential_fields.gravity.Simulation3DIntegral) tutorial. The structure and formatting requirements for tutorial notebooks are discussed below. +To ensure quality and consistency, the [Jupyter Notebooks](https://jupyter.org/) containing tutorials must follow strict structure and formatting requirements. The contents of each notebooks must be parsed sensibly into a set of sections. Sufficient explanation and links to API documentation are required when presenting functionality. Each section within a tutorial contains a combination of [Markdown](https://www.markdownguide.org/getting-started/) and coding cells. Our notebooks use the functionality in [MyST Parser](https://myst-parser.readthedocs.io/en/latest/) to augment the contents of Markdown cells. Before moving forward, we advise the contributor to: -### Introduction Markdown +* Be familiar with the structure and formatting that is used by most forward simulation and inversion tutorials. E.g. [3D Forward Simulation of Gravity Anomaly Data](../03-gravity/fwd_gravity_anomaly_3d.ipynb) and [3D Inversion of Gravity Anomaly Data](../03-gravity/inv_gravity_anomaly_3d.ipynb). -Every tutorial notebook must provide a thorough introduction. +* Refer to the Markdown syntax used by [MyST Parser](https://myst-parser.readthedocs.io/en/latest/). -#### Cell 1: Title Cell +* Refer to the [style guide](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html) for coding cells. -The first cell in the notebooks is a Markdown cell containing the title and the author for the tutorial. It is formatted as follows. + +## Notebook Introduction + +Every tutorial notebook requires an introduction section. The Markdown cells required for the introduction are described below. + +### Cell 1: Title Cell + +The first cell contains the title and the author for the tutorial. It is formatted as follows. The title is in quotations. You will need to add yourself as an author in the `myst.yml` file in the root directory of the repository. ``` @@ -20,7 +27,7 @@ authors: --- ``` -#### Cell 2: Tutorial Difficulty +### Cell 2: Tutorial Difficulty Here, we indicate whether the notebook contains introductory, intermediate or advanced content. The author is required to choose from one of the following [MyST admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html), which is rendered when the webpage is built. @@ -51,7 +58,7 @@ the user is already an experienced SimPEG user. ::: ``` -#### Cell 3: Computational Requirements +### Cell 3: Computational Requirements Here, we specify the computational requirements to run the notebook. Whereas some notebooks can be run easily on laptop computers, some notebook may need to be exported as Python files and run using cluster computing. The author is required to choose from one of the following [MyST admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html), which is rendered when the webpage is built. @@ -80,15 +87,15 @@ to a cluster computing environment. ::: ``` -#### Cell 4: Keywords, Summary and Learning Objectives +### Cell 4: Keywords, Summary and Learning Objectives -In this cell, please provide keywords relevant to the notebook. E.g. +In this cell, the contributor must provide a set of relevant keywords. E.g. ``` **Keywords:** gravity inversion, sparse-norm inversion, integral formulation, tree mesh. ``` -Next, summarize the purpose of the tutorial. The summary should be roughly one paragraph. If your tutorial focusses on particular functionality within SimPEG, please link to the API documentation. Please link to tutorials you feel the reader should have already worked through. E.g. +Next, the contributor must provide a summary of the tutorial. The summary should be roughly one paragraph. If your tutorial focusses on particular functionality within SimPEG, please link to the API documentation. Also, link to tutorials you feel the reader should have already worked through. E.g. ``` **Summary:** Here we invert gravity anomaly data to recover a density contrast model. @@ -106,7 +113,7 @@ become familiar with functionality explained in the [3D Forward Simulation of Gr Anomaly Data](fwd_gravity_anomaly_3d.ipynb) tutorial before working through this one. ``` -Finally, provide learning objectives as a bullet list. E.g. +Finally, the contributor must provide learning objectives using a bullet list. E.g. ``` **Learning Objectives:** @@ -121,21 +128,68 @@ Finally, provide learning objectives as a bullet list. E.g. - How to analyse inversion results. ``` -### Formatting Tutorial Sections +## Import Functionality + +Following the introduction section, the contributor must import all functionality used by the tutorial and briefly explain the functionality that is most important. + +### Cell 1: Header and Summary + +This Markdown cell uses the heading **Import Modules**. For functionality that relates +directly to the purpose of the tutorial, some context and a link to API documentation +should be provided. E.g. + +::: +## Import Modules + +Here, we import all of the functionality required to run the notebook for the tutorial +exercise. All of the functionality specific to simulating gravity data are imported from +[simpeg.potential_fields.gravity](xref:simpeg#simpeg.potential_fields.gravity). We also +import some useful utility functions from [simpeg.utils](xref:simpeg#simpeg.utils). +To simulate gravity data, we need to define our problem geometry on a numerical grid +(or mesh). To generate the mesh, we used the +[discretize](https://discretize.simpeg.xyz/en/main) package. +::: + +### Cell 2: Code Cell + +The coding cell where functionality is imported should be organized. E.g. + +```python +# SimPEG functionality +from simpeg.potential_fields import gravity +from simpeg.utils import plot2Ddata, model_builder +from simpeg import maps + +# discretize functionality +from discretize import TensorMesh +from discretize.utils import mkvc, active_from_xyz + +# Common Python functionality +import numpy as np +from scipy.interpolate import LinearNDInterpolator +import matplotlib as mpl + +mpl.rcParams.update({"font.size": 14}) +import matplotlib.pyplot as plt +import os +``` + +## Tutorial Sections (and Subsections) Each section (or subsection) is constructed using a combination of Markdown and code cells. The structure and formatting of these are discussed below. -#### Section Header and Summary Cell +### Cell 1: Header and Summary -Each section (or subsection) begins with a Markdown cell containing the section header and a summary. -Here, the author must: +Each section (or subsection) begins with a Markdown cell containing the header and a summary. +Here, the contributor must: * summarize what is being done in the section * describe any new functionality that is being introduced * provide links to all relevant API documentation -* describe the choices for hyperparameter values used in the tutorial. +* describe the choices for hyperparameter values used in the tutorial E.g. + ``` ## Define the Survey @@ -158,14 +212,26 @@ which are to be measured. For the tutorial simulation, the receivers are located 5 m above the surface topography and spaced 10 m apart. ``` -#### Code Block Cells: +If something has been thoroughly explained in an introductory tutorial, you can avoid repetition by linking to that tutorial. +However, the choice in values used in your tutorial should always be stated. E.g. + +``` +## Assign Uncertainties + +Approaches for applying reasonable uncertainties to normalized voltage and apparent +resistivity data were presented in the [2.5D Inversion](inv_dcr_2d.ipynb) tutorial. +Here, we apply uncertainties of 1e-7 V/A + 10 % to the normalized voltage data being +inverted. +``` + +### Code Block Cells Code blocks must follow the [style required by SimPEG](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). Please provide comments when defining new objects. This is especially important when exposing the reader to new functionality. +Avoid lengthy code blocks that can be better parsed into multiple cells. Markdown cells can also be added between code cells +to provide additional explanation to the reader. -E.g. - -``` +```python # Define the component(s) of the field we want to simulate as strings within # a list. Here we simulate only the vertical component of the gravity anomaly. components = ["gz"] @@ -183,10 +249,38 @@ source_field = gravity.sources.SourceField(receiver_list=receiver_list) survey = gravity.survey.Survey(source_field) ``` -#### Comments on Plotting: +### Comments on Plotting The author is required to plot data, models, etc... When generating plot, please ensure: * the figure renders at an appropriate size for display * the code used to generate the plot is compact -* text and features within the plot are legible \ No newline at end of file +* text and features within the plot are legible + + +## Check Style of Notebooks + +We can check the code style of our notebooks using [`ruff`][ruff] and +[`nbqa`][nbqa]. Simply run the following command to check the style of the +notebooks: + +```bash +nbqa ruff notebooks +``` + +And run this to autoformat them: + +```bash +nbqa ruff --fix notebooks +``` + +Alternatively, you can use the targets we have in the `Makefile`, like `make +check` and `make format`. Read more information about the available targets +by running `make help`. + + + + +[install-mystmd]: https://mystmd.org/guide/quickstart +[jupyter]: https://jupyter.org +[mystmd.org]: https://mystmd.org diff --git a/notebooks/generating_pr.md b/notebooks/contributing/pull_request.md similarity index 92% rename from notebooks/generating_pr.md rename to notebooks/contributing/pull_request.md index ab6d100..c713726 100644 --- a/notebooks/generating_pr.md +++ b/notebooks/contributing/pull_request.md @@ -1,5 +1,5 @@ -GitHub Pull Request and Review -============================== +GitHub Pull Request and Review Process +====================================== Requirements Checklist ---------------------- diff --git a/notebooks/contributing_index.md b/notebooks/contributing_index.md index d0d49ad..8396c63 100644 --- a/notebooks/contributing_index.md +++ b/notebooks/contributing_index.md @@ -1,32 +1,40 @@ -Contributing to User-Tutorials +Contributing to User Tutorials ============================== -User tutorials have become the primary resource for SimPEG users to learn the code base and best-practices for computational geophysics. -To ensure a high level of consistency and quality, specific guidelines need to be followed when adding new tutorial notebooks. -New tutorial notebooks will not be published until our guidelines have been followed. +SimPEG welcomes contributions by the community to improve available tutorial materials. +However, tutorials must adhere to specific guidelines in order to ensure a high level of quality and consistency. +For those interested in contributing to SimPEG User Tutorials, please follow the instructions provided. -Before You Create a Tutorial ----------------------------- -Although we greatly appreciate efforts by the SimPEG community to create new tutorials, -we must ensure the contents of the tutorial are appropriate. As a result, -we discourage tutorials that fall into the following categories: +Before Creating a New Tutorial +------------------------------ + +```{admonition} WARNING! +:class: danger +Please ensure that the contents of your tutorial **DOES NOT** fall into any of the following categories: * the tutorial focusses on functionality that is not part of SimPEG -* the amount of SimPEG functionality that has not already been covered in another tutorial is insufficient +* the amount of SimPEG functionality NOT already covered in another tutorial is insufficient * the tutorial focusses on a data-specific result and is not generalizable -* the tutorial was created for purpose of self promotion +* the tutorial was created for the purpose of self promotion + +Tutorials that fall into any of these categories will not be accepted! +``` + +Steps for Adding a Tutorial +--------------------------- + +As explained on the [SimPEG user tutorials](../index.md) landing page, the SimPEG user tutorials are a library of [Jupyter Notebooks](https://jupyter.org/) that have been published as a website using [MyST](https://mystmd.org/). To add a tutorial notebook to the project, you will need to complete the following steps: +**Step 1: Building the User Tutorials Website Locally** -How to Contribute ------------------ +First, you will need all of the functionality required to run the existing tutorial notebooks and build the website locally with [MyST][mystmd.org]. +Instructions for creating an appropriate Python environment and building the website locally are found on the [Building the User Tutorials Website Locally](contributing/build_website.md) page. -To add a new notebook to SimPEG user tutorials, you will need to complete the following three steps: +**Step 2: Creating a Tutorial Notebook** -1. Follow the instructions on the [Cloning the Repository and Building the Website](getting_started.md) page. -These instructions explain how to clone the SimPEG user tutorials repository, setup the appropriate Python -environment, and build the website locally with MyST. +Jupyter notebooks that contain tutorials must adhere to specific structure and formatting requirements. +These are provided on the [Tutorial Structure and Formatting Requirements](contributing/formatting.md) page. -2. Create a notebook according to the [Structure and Formatting for Notebooks](notebook_formatting.md) page. +**Step 3: The Review Process** -3. Create a GitHub pull request. \ No newline at end of file diff --git a/notebooks/getting_started.md b/notebooks/getting_started.md deleted file mode 100644 index 9d997d7..0000000 --- a/notebooks/getting_started.md +++ /dev/null @@ -1,135 +0,0 @@ -Cloning the Repository and Building the Website Locally -======================================================= - -## Cloning the GitHub Repository - -The GitHub repository for SimPEG User Tutorials can cloned from https://github.com/simpeg/user-tutorials/. -If using the Git Bash shell: - -```bash -git clone https://github.com/simpeg/user-tutorials -cd user-tutorials -``` - -## Setting Up Your Python Environment - -The notebooks are maintained so that they run correctly using the latest SimPEG release. Some notebooks may not -run correctly if SimPEG is being imported from an earlier release or development branch. The website is built -from the collection of Markdown files and Jupyter notebooks using [Myst][mystmd.org]. To build the website locally, -you will need to [install `mystmd`][install-mystmd] - -For contributors, an `environment.yml` file has been provided in the root directory of the repository. -To create the environment using conda: - -```bash -conda env create -f environment.yml -``` - -## How to build the website locally - -The SimPEG User Tutorials were created using [Myst][mystmd.org]. Myst is -capable of building the website from content stored in [Jupyter -Notebooks][jupyter]. - -We can build the website from the current content in the Jupyter Notebooks. -This can be done in a few seconds with very slim resource requirements. - -Rerunning the notebooks is a more intensive task that will require significant -amount of memory (specially for the computationally intensive notebooks) and it -will take some time. - -Here you'll find instructions to: - -- [Build and the website locally](#build-and-serve-the-website-locally) -- [Rerun notebooks in the repo](#rerun-notebooks) - -### Build and Serve the Website Locally - -#### Build and Serve - -The following command will build the website and serve it locally, so you can -preview it. Follow the instructions that will be prompted by the command to see -the website: - -```bash -msyt start -``` - -#### Build Only - -The following command will build the website and store the HTML files in -a new `_build` folder: - -```bash -msyt build --html -``` - -#### Clean Cached Builds - -```bash -myst clean --all -``` - -### Rerun Notebooks - -Start by cloning this repository: - -```bash -git clone https://github.com/simpeg/user-tutorials -cd user-tutorials -``` - -And create a `conda` environment using the provided `environment.yml` file: - -```bash -conda env create -f environment.yml -``` - -We can use `nbconvert` to rerun a notebook and overwrite its output cells -in place. -To rerun a single notebook, use: - -```bash -jupyter nbconvert --to notebook --execute --inplace notebook.ipynb -``` - -To rerun all notebooks, use: - -> [!CAUTION] -> Rerunning all notebooks is a computationally intensive task. Some notebooks -> require significant amount of memory to allocate large sensitivity matrices. - -> [!IMPORTANT] -> If you are using bash as your shell, make sure to run `shopt -s -> globstar` to enable the `globstar` feature that allows the use of `**` for -> filename expansion. - -```bash -jupyter nbconvert --to notebook --execute --inplace notebooks/**/*.ipynb -``` - - -[install-mystmd]: https://mystmd.org/guide/quickstart -[jupyter]: https://jupyter.org -[mystmd.org]: https://mystmd.org - - -## Check Style of Notebooks - -We can check the code style of our notebooks using [`ruff`][ruff] and -[`nbqa`][nbqa]. Simply run the following command to check the style of the -notebooks: - -```bash -nbqa ruff notebooks -``` - -And run this to autoformat them: - -```bash -nbqa ruff --fix notebooks -``` - -Alternatively, you can use the targets we have in the `Makefile`, like `make -check` and `make format`. Read more information about the available targets -by running `make help`. \ No newline at end of file From d08ad00dd72342d441d6b87b77935673a968ea88 Mon Sep 17 00:00:00 2001 From: dccowan Date: Fri, 13 Dec 2024 12:10:25 -0800 Subject: [PATCH 4/8] Finalize contributors section --- notebooks/contributing/formatting.md | 23 ++++++----- notebooks/contributing/pull_request.md | 53 +++++++++++++++++++++++--- 2 files changed, 60 insertions(+), 16 deletions(-) diff --git a/notebooks/contributing/formatting.md b/notebooks/contributing/formatting.md index eb0cd67..60ebff4 100644 --- a/notebooks/contributing/formatting.md +++ b/notebooks/contributing/formatting.md @@ -178,7 +178,7 @@ import os Each section (or subsection) is constructed using a combination of Markdown and code cells. The structure and formatting of these are discussed below. -### Cell 1: Header and Summary +### Header and Summary Each section (or subsection) begins with a Markdown cell containing the header and a summary. Here, the contributor must: @@ -249,26 +249,29 @@ source_field = gravity.sources.SourceField(receiver_list=receiver_list) survey = gravity.survey.Survey(source_field) ``` -### Comments on Plotting +### Plotting Requirements -The author is required to plot data, models, etc... When generating plot, please ensure: +The contributor is required to plot data, models and other quantities that are best understood visually. +Due to its widespread use, figures should be generated using [matplotlib](https://matplotlib.org/) package. +When generating a figure, please ensure: -* the figure renders at an appropriate size for display -* the code used to generate the plot is compact -* text and features within the plot are legible +* the figure renders at an appropriate size when building the website +* the code used to generate the figure is compact whenever possible +* the text and features within the plot are legible ## Check Style of Notebooks -We can check the code style of our notebooks using [`ruff`][ruff] and -[`nbqa`][nbqa]. Simply run the following command to check the style of the -notebooks: +We can check and autoformat the code style within the notebooks using [`ruff`][ruff] and +[`nbqa`][nbqa]. + +To check the style of the notebooks: ```bash nbqa ruff notebooks ``` -And run this to autoformat them: +To perform auto reformatting on the notebooks: ```bash nbqa ruff --fix notebooks diff --git a/notebooks/contributing/pull_request.md b/notebooks/contributing/pull_request.md index c713726..2c89fde 100644 --- a/notebooks/contributing/pull_request.md +++ b/notebooks/contributing/pull_request.md @@ -1,10 +1,12 @@ GitHub Pull Request and Review Process ====================================== +Here, we describe the pull request and review process for bring new tutorial notebooks into the SimPEG user tutorials repository. + Requirements Checklist ---------------------- -The following is a useful checklist for determining whether a new tutorial notebook follows our guidelines: +The following is a useful checklist for determining whether the tutorial notebook has satisfied formatting and structure requirements: * **The introduction is complete:** * Title and author added to notebook @@ -13,9 +15,48 @@ The following is a useful checklist for determining whether a new tutorial noteb * Summary paragraph describing the tutorial has been added * Learning objectives have been listed * Hyperlinks to other tutorial notebooks added if necessary -* **For each section:** - * Short summary of what is being done - * Newly introduced functionality is explained or a link is provided to a relevant notebook +* **For sections and subsections:** + * A header and short summary of what is being done * Links to API documentation added for all classes and functions that are used - * Data, models, etc... are plotted appropriately - * Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). \ No newline at end of file + * Newly introduced functionality is explained or links provided to relevant notebooks + * All figures are legible and rendered appropriately + * Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). + +Stages of a Pull Request +------------------------ + +When you are ready to submit your tutorial notebook review, you will make a +GitHub pull request (PR). If your pull request is not ready for a final review, +but you require feedback, please mark it as a draft pull request. Once you +feel the pull request is ready for a final review, you can convert the draft PR to +an open PR by selecting the ``Ready for review`` button at the bottom of the page. + +Once a pull request is in ``open`` status and you are ready for review, please +ping ``dccowan`` and ``santisoler`` in a github comment to +request a review. At minimum for a PR to be eligible to merge, we look for + +- Structure and formatting requirements are observed. +- The notebooks runs properly using the latest release of SimPEG. +- All reviewer comments (if any) have been addressed. +- A developer approves the PR. + +After all these steps are satisfied, a ``@simpeg/simpeg-admin`` will merge your +pull request into the main branch (feel free to ping one of us on Github). + +This being said, all SimPEG developers and admins are essentially volunteers +providing their time for the benefit of the community. This does mean that +it might take some time for us to get your PR. + +Merging a Pull Request +---------------------- + +The ``@simpeg/simpeg-admin`` will merge a Pull Request to the `main` branch +using the `Squash and Merge +`_ +strategy: all commits made to the PR branch will be _squashed_ to a single +commit that will be added to `main`. + +SimPEG admins will ensure that the commit message is descriptive and +comprehensive. Contributors can help by providing a descriptive and +comprehensive PR description of the changes that were applied and the reasons +behind them. This will be greatly appreciated. \ No newline at end of file From eed4dc84c4c60ab7fb0971f8a632f69508ac4013 Mon Sep 17 00:00:00 2001 From: dccowan Date: Fri, 13 Dec 2024 12:14:18 -0800 Subject: [PATCH 5/8] update PR template --- .github/pull_request_template.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 26b2b71..16c896e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,26 +14,24 @@ Feel free to remove lines from this template that do not apply to you pull reque --> #### Summary - + #### PR Checklist * [ ] If this is a work in progress PR, set as a Draft PR * [ ] Introduction is complete: - * [ ] Author has been added to notebook - * [ ] An introductory paragraph summarizing the notebook's contents has been added - * [ ] Appropriate admonitions for notebook difficulty and computational resources have been added - * [ ] Appropriate keywords have been added - * [ ] Learning objectives have been listed - * [ ] Hyperlinks to other tutorial notebooks and important classes/functionality have been added -* [ ] Each section is properly formatted - * [ ] Short summary of what is being done - * [ ] Newly introduced functionality is explained or a link is provided to a relevant notebook - * [ ] Links to API documentation added for all classes and functionality - * [ ] Data, models, etc... are plotted whenever possible -* [ ] Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). -* [ ] Added [tests](https://docs.simpeg.xyz/latest/content/getting_started/contributing/testing.html) to verify changes to the code. -* [ ] Marked as ready for review (if this is was a draft PR), and converted - to a Pull Request + * [ ] Title and author added to notebook + * [ ] Admonitions for notebook difficulty and computational resources have been added + * [ ] Keywords list has been added + * [ ] Summary paragraph describing the tutorial has been added + * [ ] Learning objectives have been listed + * [ ] Hyperlinks to other tutorial notebooks added if necessary +* [ ] For sections and subsections: + * [ ] A header and short summary of what is being done + * [ ] Links to API documentation added for all classes and functions that are used + * [ ] Newly introduced functionality is explained or links provided to relevant notebooks + * [ ] All figures are legible and rendered appropriately + * [ ] Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). +* [ ] Marked as ready for review (if this is was a draft PR), and converted to a pull request * [ ] Tagged ``@simpeg/simpeg-developers`` when ready for review. From db6472789d2cd820d3b4a007f40d48e167f3f9a8 Mon Sep 17 00:00:00 2001 From: Santiago Soler Date: Mon, 16 Dec 2024 15:09:59 -0800 Subject: [PATCH 6/8] Update instructions to check style of notebooks --- notebooks/contributing/formatting.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/notebooks/contributing/formatting.md b/notebooks/contributing/formatting.md index 60ebff4..656a33d 100644 --- a/notebooks/contributing/formatting.md +++ b/notebooks/contributing/formatting.md @@ -262,28 +262,30 @@ When generating a figure, please ensure: ## Check Style of Notebooks -We can check and autoformat the code style within the notebooks using [`ruff`][ruff] and -[`nbqa`][nbqa]. +We can check the code style of our notebooks using [`ruff`][ruff]. +Simply run the following command to check the style of the notebooks: -To check the style of the notebooks: +```bash +ruff check notebooks +``` + +You can run the following that the notebooks are correctly formatted: ```bash -nbqa ruff notebooks +ruff format --check notebooks ``` -To perform auto reformatting on the notebooks: +And run this to autoformat them: ```bash -nbqa ruff --fix notebooks +ruff format --fix notebooks ``` Alternatively, you can use the targets we have in the `Makefile`, like `make check` and `make format`. Read more information about the available targets by running `make help`. - - - +[ruff]: https://astral.sh/ruff [install-mystmd]: https://mystmd.org/guide/quickstart [jupyter]: https://jupyter.org [mystmd.org]: https://mystmd.org From 7762b25b59ab17e8f8fdef5e5098097d8dd35e6a Mon Sep 17 00:00:00 2001 From: dccowan Date: Wed, 18 Dec 2024 15:18:38 -0800 Subject: [PATCH 7/8] update template --- .github/pull_request_template.md | 3 ++- notebooks/contributing/pull_request.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 16c896e..0bceb21 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -28,7 +28,8 @@ Feel free to remove lines from this template that do not apply to you pull reque * [ ] For sections and subsections: * [ ] A header and short summary of what is being done * [ ] Links to API documentation added for all classes and functions that are used - * [ ] Newly introduced functionality is explained or links provided to relevant notebooks + * [ ] Newly introduced functionality is explained, or links are provided to relevant materials + * [ ] The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged. * [ ] All figures are legible and rendered appropriately * [ ] Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). * [ ] Marked as ready for review (if this is was a draft PR), and converted to a pull request diff --git a/notebooks/contributing/pull_request.md b/notebooks/contributing/pull_request.md index 2c89fde..9276834 100644 --- a/notebooks/contributing/pull_request.md +++ b/notebooks/contributing/pull_request.md @@ -18,7 +18,8 @@ The following is a useful checklist for determining whether the tutorial noteboo * **For sections and subsections:** * A header and short summary of what is being done * Links to API documentation added for all classes and functions that are used - * Newly introduced functionality is explained or links provided to relevant notebooks + * Newly introduced functionality is explained, or links are provided to relevant materials + * The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged. * All figures are legible and rendered appropriately * Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). From 794f7aa2620fcff3c08d78aaccf91cbb5d3c1cf2 Mon Sep 17 00:00:00 2001 From: dccowan Date: Thu, 19 Dec 2024 10:41:39 -0800 Subject: [PATCH 8/8] Update checklist --- .github/pull_request_template.md | 9 ++++++--- notebooks/contributing/pull_request.md | 7 +++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0bceb21..d9998d8 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -18,6 +18,10 @@ Feel free to remove lines from this template that do not apply to you pull reque #### PR Checklist * [ ] If this is a work in progress PR, set as a Draft PR +* [ ] General + * [ ] Notebook is compatible with latest SimPEG release + * [ ] No deprecated functions and/or input arguments are being used + * [ ] Coding cells linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). * [ ] Introduction is complete: * [ ] Title and author added to notebook * [ ] Admonitions for notebook difficulty and computational resources have been added @@ -29,11 +33,10 @@ Feel free to remove lines from this template that do not apply to you pull reque * [ ] A header and short summary of what is being done * [ ] Links to API documentation added for all classes and functions that are used * [ ] Newly introduced functionality is explained, or links are provided to relevant materials - * [ ] The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged. + * [ ] The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged * [ ] All figures are legible and rendered appropriately - * [ ] Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). * [ ] Marked as ready for review (if this is was a draft PR), and converted to a pull request -* [ ] Tagged ``@simpeg/simpeg-developers`` when ready for review. +* [ ] Tagged ``@simpeg/simpeg-developers`` when ready for review #### Additional information diff --git a/notebooks/contributing/pull_request.md b/notebooks/contributing/pull_request.md index 9276834..79d8026 100644 --- a/notebooks/contributing/pull_request.md +++ b/notebooks/contributing/pull_request.md @@ -8,6 +8,10 @@ Requirements Checklist The following is a useful checklist for determining whether the tutorial notebook has satisfied formatting and structure requirements: +* **General:** + * Notebook is compatible with latest SimPEG release + * No deprecated functions and/or input arguments are being used + * Coding cells linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). * **The introduction is complete:** * Title and author added to notebook * Admonitions for notebook difficulty and computational resources have been added @@ -19,9 +23,8 @@ The following is a useful checklist for determining whether the tutorial noteboo * A header and short summary of what is being done * Links to API documentation added for all classes and functions that are used * Newly introduced functionality is explained, or links are provided to relevant materials - * The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged. + * The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged * All figures are legible and rendered appropriately - * Coding cells have been linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html). Stages of a Pull Request ------------------------