Readme and actions updates

CODE_OF_CONDUCT.md

@@ -5,7 +5,7 @@
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
+identity and expression, level of experience, education, socioeconomic status,
 nationality, personal appearance, race, religion, or sexual identity
 and orientation.
 

README.md

@@ -9,3 +9,64 @@
 
 This repository stores a skeleton of a GeoSMART use case book.<br>
 Click on "use this template" to get started.
+
+## How to use this template
+
+This repository is a template for creating a GeoSMART use case book. These use the Jupyter Book format, documentation for which can be found [here](https://jupyterbook.org/en/stable/intro.html). Jupyter Book websites are built using Jupyter Notebook (`.ipynb`) and markdown (`.md`) files.
+
+### Create a new repository from this template
+1. On the top right of the page, click *Use this template* and then *Create a new repository*
+1. This should take you to a new page titled *Create a new repository*
+1. Double check that the dropdown menu below *Repository template* says either *geo-smart/simple-template* or *geo-smart/use_case_template*
+1. Leave the box unchecked for *Include all branches*
+1. For *Owner* select your github user account, or another organization to create the new repository under
+1. Give your use case repository a name under *Repository name*
+1. Add a short *Description*
+1. Select the option for *Public*
+1. Finally, click *Create repository*
+
+### Configure your new use case repository
+
+With your new use case repository, you can choose to clone the repository to work on your local system, or edit configuration files within the web browser.
+
+In the `book` directory, update the `_config.yml` file with some basic information:
+- `title: `
+- `author: `
+- `myst_substitutions:` `website_url: `
+- `repository:` `url: `
+
+Note that the values for `website_url` and `url` above will NOT be the same. The `website_url` is the url to the rendered Jupyter Book website (e.g. `https://example.github.io/my-jupyterbook`), while `repository:` `url:` is the url to the GitHub repository (e.g. `https://github.com/example/my-jupyterbook`). You can leave all the other configuration options unchanged for now.
+
+### Setup GitHub Action to build the JupyterBook
+
+1. In your repository *Settings* (gear icon on top of your repository's page), go to the *Pages* section.
+1. Under the *Build and deployment* settings, click on the dropdown menu below *Source* and select *Deploy from a branch*.
+1. Under the *Branch* section that appears below, change the selected branch from `main` to `gh-pages` in the first dropdown menu. Leave the second dropdown menu set to `/ (root)`
+1. Then go to the *Actions* section of the repository's settings.
+1. Under the *Workflow permissions* settings, select the *Read and write permissions* option.
+
+
+Your JupyterBook is now configured to build and deploy following each new commit you make to the repository. Note: The file that runs the build and deploy action is located at `/.github/actions/buildresources/action.yaml` but **you do not need to make any changes to this file**.
+
+If a commit fails to produce a new version of the Book, go to the *Actions* tab on the GitHub repository page to read the action logs and diagnose errors (failed actions will have a red icon with an X next to them).
+
+### Add your use case content
+
+Now that you have completed the creation, configuration, and setup steps, you can begin adding your use case content to the JupyterBook. 
+
+* update the `environment.yml` file to include any packages that your use case code will require (the Jupyter Notebooks are executed with this environment each time the GitHub action that builds and deploys the website is ran).
+* `book/intro.md` is where you can add content for your Jupyter Book's home page
+* `book/chapters/` will contain markdown or Jupyter Notebook files, the main content of your use case Jupyter Book
+    * This template contains placeholder Jupyter Notebook files to illustrate a recommended way to organize your content. You can edit each of these files to add your content following the suggested organization, or remove and replace the placeholder files with your own content.
+* Update the table of contents file (`/book/_toc.yml`) to organize page navigation through the website
+  * Jupyter Books organize content by *Parts*, and within each part are *Chapters*. A chapter consists of a single Jupyter Notebook or markdown file.
+  * You create and title parts in the table of contents file with `- caption: Part Title`
+  * Under each part you can list one or more chapters using `- file: chapters/my_file` which points to either `my_file.ipynb` or `my_file.md`
+
+## Other resources
+
+We recommend that you refer to the JupyterBook documentation on the following topics to help your organize your content:
+* [Structure](https://jupyterbook.org/en/stable/structure/toc.html) and [Configure](https://jupyterbook.org/en/stable/structure/configure.html) the table of contents, `book/_toc.yml`
+* [Markdown](https://jupyterbook.org/en/stable/file-types/markdown.html) and [Jupyter Notebook](https://jupyterbook.org/en/stable/file-types/notebooks.html) files for the content in `book/chapters/`
+* Embedding [images and figures](https://jupyterbook.org/en/stable/content/figures.html) from `book/img/`, and writing inline [math and equations](https://jupyterbook.org/en/stable/content/math.html)
+* [Links and references](https://jupyterbook.org/en/stable/content/references.html), [special content blocks](https://jupyterbook.org/en/stable/content/content-blocks.html), and more ways to [structure chunks of content](https://jupyterbook.org/en/stable/content/components.html)

book/chapters/conclusion.ipynb

@@ -19,7 +19,7 @@
     "\n",
     "This chapter has two parts: lessons learnt and open questions. \n",
     "\n",
-    "Learns learnt should summerize the new stuff we learn from this use case of AI. What new contribution does AI give to solve this problem? Is it good enough to achieve your expected goal? What part of work is unexpected before you dive in? Do you think the model can work in your production environment? etc.\n",
+    "Learns learnt should summarize the new stuff we learn from this use case of AI. What new contribution does AI give to solve this problem? Is it good enough to achieve your expected goal? What part of work is unexpected before you dive in? Do you think the model can work in your production environment? etc.\n",
     "\n",
     "Open questions should focus on future possibilities like if your team wants to adopt this model, what else you should do to make it fully work? How should we better tackle the data bias problem? How should we address the generalization issue on spatial and temporal extent in practice?\n",
     "\n",

book/chapters/development.ipynb

@@ -7,9 +7,9 @@
     "tags": []
    },
    "source": [
-    "# Model Development and Paramter Tuning\n",
+    "# Model Development and Parameter Tuning\n",
     "\n",
-    "Explain the effects of parameter tuning and how it was performed. If you used a tool to perform automatic tuning , explaing that as well. If it is the case, explain model under or over fitting and the consequences.\n"
+    "Explain the effects of parameter tuning and how it was performed. If you used a tool to perform automatic tuning , explaining that as well. If it is the case, explain model under or over fitting and the consequences.\n"
    ]
   }
  ],

book/chapters/troubleshooting.ipynb

@@ -10,7 +10,7 @@
     "\n",
     "If you have no issues with running the tutorials, you can skip this chapter. It is very likely that some platform specific issues happen now and then, we would love to collect those knowledge to help students in future to avoid wasting time on them. \n",
     "\n",
-    "In this chapter, each section should address one techincal issue/concern. Please list your running environment in many details as possible. The following is an example:"
+    "In this chapter, each section should address one technical issue/concern. Please list your running environment in many details as possible. The following is an example:"
    ]
   },
   {