preliminary contributors instructions

Author: dccowan

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

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,

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.

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).

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`.