From 8153bb5b8f2933da6db22a7c7733bfb8c891fd85 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Thu, 12 Sep 2024 16:30:12 -0700 Subject: [PATCH 01/11] Update with detailed instructions --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/README.md b/README.md index eea7669..bc3d8d0 100644 --- a/README.md +++ b/README.md @@ -9,3 +9,60 @@ This repository stores a skeleton of a GeoSMART use case book.
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* +2. This should take you to a new page titled *Create a new repository* +3. Double check that the dropdown menu below *Repository template* says either *geo-smart/simple-template* or *geo-smart/use_case_template* +4. Leave the box unchecked for *Include all branches* +5. For *Owner* select your github user account, or another organization to create the new repository under +6. Give your use case repository a name under *Repository name* +7. Add a short *Description* +8. Select the option for *Public* +9. 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: ` +- `repository:` `url: ` + +You can leave all the other configuration options unchanged for now. + +### Setup GitHub Action to build the JupyterBook + +In your repository *Settings* (gear icon on top of your repository's page), go to the *Pages* section. + +Under the *Build and deployment* settings, click on the dropdown menu below *Source* and select *GitHub Actions*. + +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/workflows/publish.yml` 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/` +* Embeding [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) From 2b96f739797c5e8dbee6db639a4376e3a6bd3af1 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Thu, 12 Sep 2024 16:38:31 -0700 Subject: [PATCH 02/11] Clarify url differences --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bc3d8d0..ca19b7b 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,10 @@ With your new use case repository, you can choose to clone the repository to wor In the `book` directory, update the `_config.yml` file with some basic information: - `title: ` - `author: ` +- `myst_substitutions:` `website_url: ` - `repository:` `url: ` -You can leave all the other configuration options unchanged for now. +Note that the values for `website_url` and `url` above will NOTE 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 From cc46c2b7bf3e8972091cc4db3ece93fe2db5325e Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Thu, 12 Sep 2024 16:43:22 -0700 Subject: [PATCH 03/11] Fix typo --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ca19b7b..32fe5f1 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ In the `book` directory, update the `_config.yml` file with some basic informati - `myst_substitutions:` `website_url: ` - `repository:` `url: ` -Note that the values for `website_url` and `url` above will NOTE 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. +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 @@ -43,7 +43,7 @@ In your repository *Settings* (gear icon on top of your repository's page), go t Under the *Build and deployment* settings, click on the dropdown menu below *Source* and select *GitHub Actions*. -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/workflows/publish.yml` but **you do not need to make any changes to this file**. +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). From 239ae18d2205735f570a9a64fd21d6183084ae96 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Thu, 12 Sep 2024 17:13:46 -0700 Subject: [PATCH 04/11] Update README.md --- README.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 32fe5f1..deba7e1 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,14 @@ This repository is a template for creating a GeoSMART use case book. These use t ### 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* -2. This should take you to a new page titled *Create a new repository* -3. Double check that the dropdown menu below *Repository template* says either *geo-smart/simple-template* or *geo-smart/use_case_template* -4. Leave the box unchecked for *Include all branches* -5. For *Owner* select your github user account, or another organization to create the new repository under -6. Give your use case repository a name under *Repository name* -7. Add a short *Description* -8. Select the option for *Public* -9. Finally, click *Create 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 @@ -39,9 +39,11 @@ Note that the values for `website_url` and `url` above will NOT be the same. The ### Setup GitHub Action to build the JupyterBook -In your repository *Settings* (gear icon on top of your repository's page), go to the *Pages* section. +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 *GitHub Actions*. +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. -Under the *Build and deployment* settings, click on the dropdown menu below *Source* and select *GitHub Actions*. 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**. From 679b387d0d58c07e35aaaf5a9ca40505ed89728e Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Thu, 12 Sep 2024 17:31:45 -0700 Subject: [PATCH 05/11] Update README.md --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index deba7e1..8dfbf79 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,8 @@ Note that the values for `website_url` and `url` above will NOT be the same. The ### 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 *GitHub Actions*. +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. From 28844b9a4cd170d9b1dfeadef098f615f39e232d Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:45:40 -0700 Subject: [PATCH 06/11] Fix spelling --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8dfbf79..370a16d 100644 --- a/README.md +++ b/README.md @@ -68,5 +68,5 @@ Now that you have completed the creation, configuration, and setup steps, you ca 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/` -* Embeding [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) +* 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) From b06528462bf0e24cac0572324a6e927365240602 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:46:19 -0700 Subject: [PATCH 07/11] Fix spelling --- book/chapters/conclusion.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/chapters/conclusion.ipynb b/book/chapters/conclusion.ipynb index 68ccb1f..9d63f1b 100644 --- a/book/chapters/conclusion.ipynb +++ b/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", From cb55a29adafe9c17393174d7509fc9f83db41947 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:46:45 -0700 Subject: [PATCH 08/11] Fix spelling --- book/chapters/development.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/chapters/development.ipynb b/book/chapters/development.ipynb index b6afd01..8ba978b 100644 --- a/book/chapters/development.ipynb +++ b/book/chapters/development.ipynb @@ -7,7 +7,7 @@ "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" ] From c2e74acdd2406df2fc99c9c3e8958f2b5ebbe6a3 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:47:06 -0700 Subject: [PATCH 09/11] Update development.ipynb --- book/chapters/development.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/chapters/development.ipynb b/book/chapters/development.ipynb index 8ba978b..998e743 100644 --- a/book/chapters/development.ipynb +++ b/book/chapters/development.ipynb @@ -9,7 +9,7 @@ "source": [ "# 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" ] } ], From 1e9ba3a93750f1989f9860ac9a206548a03940a0 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:47:43 -0700 Subject: [PATCH 10/11] Fix spelling --- book/chapters/troubleshooting.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/chapters/troubleshooting.ipynb b/book/chapters/troubleshooting.ipynb index c6b8b67..35f6588 100644 --- a/book/chapters/troubleshooting.ipynb +++ b/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:" ] }, { From 6e167446974285b6f0a4e5df69a6a4f661eabe89 Mon Sep 17 00:00:00 2001 From: Steven Pestana <650301+spestana@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:48:40 -0700 Subject: [PATCH 11/11] Fix spelling --- CODE_OF_CONDUCT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 61c150f..3dec140 100644 --- a/CODE_OF_CONDUCT.md +++ b/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.