From 3d93488a696f152873118ff1536ad52060d2e0fe Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 11 Dec 2024 17:45:42 +0100 Subject: [PATCH 01/21] Create exercises.md --- book/some_content/exercises.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 book/some_content/exercises.md diff --git a/book/some_content/exercises.md b/book/some_content/exercises.md new file mode 100644 index 0000000..c3fe8f3 --- /dev/null +++ b/book/some_content/exercises.md @@ -0,0 +1,3 @@ +# Exercises + +This pages will contain some exercises! \ No newline at end of file From 49556320bc41864935e49e2f5b0b328905246d79 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:05:34 +0100 Subject: [PATCH 02/21] Update intro.md --- book/intro.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/book/intro.md b/book/intro.md index 6df898f..5c76b4d 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,6 +1,20 @@ (intro)= # Welcome to the Template Book -_Write book intro here. This is the first page the student will see when opening the url._ +_This is the first page the student will see when opening the url._ -This book can be used as a template for other books. It includes a starter package of the software developed by the TeachBooks initiative. \ No newline at end of file +This book can be used as a template for other books. It includes a starter package of the software developed by the TeachBooks initiative and some exercises to get you going! + +```{admonition} Exercise 1: Edit contents +:class: tip + +Can you add some content to this page? Let's start with just some text! + +1. Go to the source file of this page on your GitHub repository - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` +2. Add some text +3. Click `Commit changes` +4. Add a description of your change +5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) +6. Click `Commit changes` +7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the name of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` +``` \ No newline at end of file From b14cee5ddbcbf4e63cf0ff7763ff1eb6f959be03 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:08:39 +0100 Subject: [PATCH 03/21] Update intro.md --- book/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/intro.md b/book/intro.md index 5c76b4d..d591048 100644 --- a/book/intro.md +++ b/book/intro.md @@ -10,7 +10,7 @@ This book can be used as a template for other books. It includes a starter packa Can you add some content to this page? Let's start with just some text! -1. Go to the source file of this page on your GitHub repository - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` +1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` 2. Add some text 3. Click `Commit changes` 4. Add a description of your change From 8a676bad228d19eb203146dcd9602e30fc831102 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:16:50 +0100 Subject: [PATCH 04/21] Update intro.md --- book/intro.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/intro.md b/book/intro.md index d591048..26cfa66 100644 --- a/book/intro.md +++ b/book/intro.md @@ -11,10 +11,11 @@ This book can be used as a template for other books. It includes a starter packa Can you add some content to this page? Let's start with just some text! 1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` -2. Add some text +2. Add some text. You want to be create already, have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) 3. Click `Commit changes` 4. Add a description of your change 5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) 6. Click `Commit changes` 7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the name of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` +8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). ``` \ No newline at end of file From 3ed48d048456105b58a56c481b0dd531d63c546e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:20:52 +0100 Subject: [PATCH 05/21] Added exercises separately --- book/_toc.yml | 3 +++ book/exercises/001.md | 25 +++++++++++++++++++++++++ book/exercises/exercises.md | 3 +++ book/intro.md | 17 +---------------- book/some_content/exercises.md | 3 --- 5 files changed, 32 insertions(+), 19 deletions(-) create mode 100644 book/exercises/001.md create mode 100644 book/exercises/exercises.md delete mode 100644 book/some_content/exercises.md diff --git a/book/_toc.yml b/book/_toc.yml index a28474b..3334e7b 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -7,6 +7,9 @@ parts: - file: some_content/overview.md sections: - file: some_content/text_and_code.ipynb + - file: exercises/exercises + sections: + - file: exercises/001.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/001.md b/book/exercises/001.md new file mode 100644 index 0000000..414eb9c --- /dev/null +++ b/book/exercises/001.md @@ -0,0 +1,25 @@ +# Exercise 1: First file edit + +Let's start with the most basic edit: add some text to a file and see that the website is updated. This exercise is ready for you at https://teachbooks.io/template/exercises/001 + +Can you add some content to the intro page? Let's start with just some text! + +1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` +2. Add some text. You want to be create already, have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) +3. Click `Commit changes` +4. Add a description of your change +5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) +6. Click `Commit changes` +7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the name of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` +8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). + +```{admonition} Check your understanding +:class: tip + +Before moving on to the next exercise, make sure you understand the following: +1. Where are the contents of the book stored? +2. How can you edit a single file via the GitHub browser interface? +3. What is a commit and what role does it play in the editing process? +4. Given a specific GitHub repository, can you determine the URL of the book website? +5. Where is the book metadata stored? +``` \ No newline at end of file diff --git a/book/exercises/exercises.md b/book/exercises/exercises.md new file mode 100644 index 0000000..7603399 --- /dev/null +++ b/book/exercises/exercises.md @@ -0,0 +1,3 @@ +# Exercises + +Want to get started making books? Follow these exercises! \ No newline at end of file diff --git a/book/intro.md b/book/intro.md index 26cfa66..565494d 100644 --- a/book/intro.md +++ b/book/intro.md @@ -3,19 +3,4 @@ _This is the first page the student will see when opening the url._ -This book can be used as a template for other books. It includes a starter package of the software developed by the TeachBooks initiative and some exercises to get you going! - -```{admonition} Exercise 1: Edit contents -:class: tip - -Can you add some content to this page? Let's start with just some text! - -1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` -2. Add some text. You want to be create already, have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) -3. Click `Commit changes` -4. Add a description of your change -5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) -6. Click `Commit changes` -7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the name of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` -8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). -``` \ No newline at end of file +This book can be used as a template for other books. It includes a starter package of the software developed by the TeachBooks initiative and some exercises to get you going! \ No newline at end of file diff --git a/book/some_content/exercises.md b/book/some_content/exercises.md deleted file mode 100644 index c3fe8f3..0000000 --- a/book/some_content/exercises.md +++ /dev/null @@ -1,3 +0,0 @@ -# Exercises - -This pages will contain some exercises! \ No newline at end of file From f7da7b41881a43fd66c4c81c3313f360aeb56c03 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:22:08 +0100 Subject: [PATCH 06/21] Update 001.md --- book/exercises/001.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index 414eb9c..9137852 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -1,8 +1,8 @@ # Exercise 1: First file edit -Let's start with the most basic edit: add some text to a file and see that the website is updated. This exercise is ready for you at https://teachbooks.io/template/exercises/001 +Let's start with the most basic edit: add some text to a file and see that the website is updated. -Can you add some content to the intro page? Let's start with just some text! +Can you add some content to the intro page? 1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` 2. Add some text. You want to be create already, have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) @@ -21,5 +21,4 @@ Before moving on to the next exercise, make sure you understand the following: 2. How can you edit a single file via the GitHub browser interface? 3. What is a commit and what role does it play in the editing process? 4. Given a specific GitHub repository, can you determine the URL of the book website? -5. Where is the book metadata stored? ``` \ No newline at end of file From dfc7449f4e77af0da0e18ad8882147ba07a87067 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:23:29 +0100 Subject: [PATCH 07/21] Update 001.md --- book/exercises/001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index 9137852..ad66766 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -5,7 +5,7 @@ Let's start with the most basic edit: add some text to a file and see that the w Can you add some content to the intro page? 1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` -2. Add some text. You want to be create already, have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) +2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! 3. Click `Commit changes` 4. Add a description of your change 5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) From d83e4018ad5fd6f6f88f66f9d7a6936a7929ec98 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:42:58 +0100 Subject: [PATCH 08/21] Added more exercises --- book/_toc.yml | 1 + book/exercises/001.md | 6 ++-- book/exercises/002.md | 56 +++++++++++++++++++++++++++++++++++ book/some_content/overview.md | 2 +- 4 files changed, 61 insertions(+), 4 deletions(-) create mode 100644 book/exercises/002.md diff --git a/book/_toc.yml b/book/_toc.yml index 3334e7b..41c8f76 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -10,6 +10,7 @@ parts: - file: exercises/exercises sections: - file: exercises/001.md + - file: exercises/002.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/001.md b/book/exercises/001.md index ad66766..e9fecb9 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -4,13 +4,13 @@ Let's start with the most basic edit: add some text to a file and see that the w Can you add some content to the intro page? -1. Go to the source file of this page on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` +1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` 2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! 3. Click `Commit changes` -4. Add a description of your change +4. Add a message and description of your change 5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) 6. Click `Commit changes` -7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the name of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` +7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit messageof the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` 8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). ```{admonition} Check your understanding diff --git a/book/exercises/002.md b/book/exercises/002.md new file mode 100644 index 0000000..e080436 --- /dev/null +++ b/book/exercises/002.md @@ -0,0 +1,56 @@ +# Exercise 1: Add a new file to the table of contents + +Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's create a new file and add it to that list! + +Can you create a file named `my_first_file.md` and add it successfully to the book? + +1. Go to the `/book` directory of your GitHub repository and add a file (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - `Add file` - {octicon}`plus;1em` `Create new file` +2. Name your file `my_first_file.md`. Don't forget the `.md`! +3. In the `Edit` field, start the first line with the header of your page (each file needs to have a header which will be the title shown in the table of contents): +```md +# Title of my first file +``` +4. On a new line, add some more text so that you end up with something like: + +```md +# Title of my first file +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id diam non mauris auctor sollicitudin. Ut quis nunc lobortis, iaculis massa id, eleifend justo. Nulla ac auctor sapien. Etiam sit amet est a ex vestibulum porta. Nulla non lacus a purus luctus blandit sit amet non nibh. Curabitur vitae cursus dolor. Ut eu nisi nec enim ullamcorper fermentum. +``` +5. Want to view all the text without horizontal scrolling? Click `No wrap` and select `Soft wrap` +6. Click `Commit changes` +7. Add a message and description of your change +8. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) +9. Click `Commit changes` +10. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` +11. Add this file as a second item in the `Some content` chapter + +````{admonition} Need some help? +:class: tip, dropdown +Your `_toc.yml` should look like +```yml +... +parts: + - caption: Contents + chapters: + - file: some_content/overview.md + sections: + - file: some_content/text_and_code.ipynb + - file: my_first_file.md +... +``` +```` +12. Click `Commit changes` +13. Add a message and description of your change +14. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) +15. Click `Commit changes` +16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting, there'll be exercising on doing this locally which prevents you from waiting) +17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). + +```{admonition} Check your understanding +:class: tip + +Before moving on to the next exercise, make sure you understand the following: +1. Are all files in the repository added to the website? +2. How many commits does it take to add a file online? +3. What needs to be on a page at least to be edit to the book? +``` \ No newline at end of file diff --git a/book/some_content/overview.md b/book/some_content/overview.md index 5adab4e..ec79e50 100644 --- a/book/some_content/overview.md +++ b/book/some_content/overview.md @@ -1,3 +1,3 @@ -# Overview +# Some content Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. \ No newline at end of file From 505dd3ccf59473a2b1c9512254c3332ca61626a0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 15:49:45 +0100 Subject: [PATCH 09/21] WIP --- book/exercises/001.md | 3 +-- book/exercises/002.md | 22 +++++++++++++++++----- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index e9fecb9..15e23e7 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -13,8 +13,7 @@ Can you add some content to the intro page? 7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit messageof the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` 8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). -```{admonition} Check your understanding -:class: tip +```{note} Check your understanding Before moving on to the next exercise, make sure you understand the following: 1. Where are the contents of the book stored? diff --git a/book/exercises/002.md b/book/exercises/002.md index e080436..ea0d7ec 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -1,4 +1,4 @@ -# Exercise 1: Add a new file to the table of contents +# Exercise 2: Add a new file to the table of contents Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's create a new file and add it to that list! @@ -28,7 +28,9 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id diam non maur :class: tip, dropdown Your `_toc.yml` should look like ```yml -... +format: jb-book +root: intro.md + parts: - caption: Contents chapters: @@ -36,7 +38,18 @@ parts: sections: - file: some_content/text_and_code.ipynb - file: my_first_file.md -... + - file: exercises/exercises + sections: + - file: exercises/001.md + - file: exercises/002.md + - file: exercises/003.md + - file: exercises/004.md + - file: exercises/005.md + - file: exercises/006.md + - file: exercises/007.md + - file: references.md + - file: changelog.md + - file: credits.md ``` ```` 12. Click `Commit changes` @@ -46,8 +59,7 @@ parts: 16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting, there'll be exercising on doing this locally which prevents you from waiting) 17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). -```{admonition} Check your understanding -:class: tip +```{note} Check your understanding Before moving on to the next exercise, make sure you understand the following: 1. Are all files in the repository added to the website? From c04fcb7b6ce7e416bbf58489653b8194ccd135ef Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 16:13:30 +0100 Subject: [PATCH 10/21] Added more exercises --- book/_config.yml | 1 - book/exercises/002.md | 2 +- book/exercises/003.md | 45 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 book/exercises/003.md diff --git a/book/_config.yml b/book/_config.yml index 2cd6a78..744a3b5 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,4 +1,3 @@ -title: Template author: TeachBooks Team, built with TeachBooks and Jupyter Book, CC BY 4.0 #add your own name here execute: diff --git a/book/exercises/002.md b/book/exercises/002.md index ea0d7ec..8e0c134 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -56,7 +56,7 @@ parts: 13. Add a message and description of your change 14. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) 15. Click `Commit changes` -16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting, there'll be exercising on doing this locally which prevents you from waiting) +16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) 17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). ```{note} Check your understanding diff --git a/book/exercises/003.md b/book/exercises/003.md new file mode 100644 index 0000000..d916416 --- /dev/null +++ b/book/exercises/003.md @@ -0,0 +1,45 @@ +# Exercise 3: Change book configuration + +As we've added some content by now, let's make this book a bit more personal! We'll make some changes to the `_config.yml` file which changes the configuration of the book website. + +Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? + +1. Go to the the file `book/_config.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_config.yml` - {octicon}`pencil;1em` `Edit this file` +2. In the `Edit` field, change the author which will be shown in the footer of the book website. +````{admonition} Need some help? +:class: tip, dropdown +The first line of your `_config.yml` should look like +```yml +author: , built with TeachBooks and Jupyter Book, CC BY 4.0 +``` +```` +3. In the `Edit` field, change the title of your homepage which will under the logo and above the table of contents +````{admonition} Need some help? +:class: tip, dropdown +The 21st line of your `_config.yml` should look like +```yml + text: +``` +```` +4. In the `Edit` field, change the repository url which will be used to allow other people to open your repository, suggest edits and open issues as shown in top right corner of the built book under {octicon}`mark-github;1em`. +````{admonition} Need some help? +:class: tip, dropdown +The 24th line of your `_config.yml` should look like +```yml + repository_url: "https://github.com//" +``` +```` +5. Click `Commit changes` +6. Add a message and description of your change +7. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) +8. Click `Commit changes` +9. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _config.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) +10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). + +```{note} Check your understanding + +Before moving on to the next exercise, make sure you understand the following: +1. What is this special `_config.yml` file? +2. Changes in `_config.yml` can have effect on multiple pages in the book +3. The `_config.yml` is generally not used for adding content +``` \ No newline at end of file From 762d52c99cc40da42d73305139b9238eac579409 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 16:16:17 +0100 Subject: [PATCH 11/21] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index 41c8f76..4c5006b 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -11,6 +11,7 @@ parts: sections: - file: exercises/001.md - file: exercises/002.md + - file: exercises/003.md - file: references.md - file: changelog.md - file: credits.md From 6531c4f63b6f5a804331d64ca93ffb59adf8820d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 16:42:52 +0100 Subject: [PATCH 12/21] added exercise 4 --- book/_toc.yml | 1 + book/exercises/001.md | 14 ++++++++------ book/exercises/002.md | 9 +++++---- book/exercises/003.md | 10 +++++----- book/exercises/004.md | 25 +++++++++++++++++++++++++ 5 files changed, 44 insertions(+), 15 deletions(-) create mode 100644 book/exercises/004.md diff --git a/book/_toc.yml b/book/_toc.yml index 4c5006b..8e6ddf2 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -12,6 +12,7 @@ parts: - file: exercises/001.md - file: exercises/002.md - file: exercises/003.md + - file: exercises/004.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/001.md b/book/exercises/001.md index 15e23e7..4191b53 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -7,17 +7,19 @@ Can you add some content to the intro page? 1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` 2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! 3. Click `Commit changes` -4. Add a message and description of your change +4. Add a message and description of your change. With this `commit` you save your changes to the git-timeline. Any commit can always be reverted. Therefore, it's useful to shortly explain what is included in your commit. Later on, you'll make commits which may contain changes to many different files. In that case, a descriptive commit message and description is even more useful! 5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) -6. Click `Commit changes` +6. Click `Commit changes`. 7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit messageof the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` 8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). ```{note} Check your understanding Before moving on to the next exercise, make sure you understand the following: -1. Where are the contents of the book stored? -2. How can you edit a single file via the GitHub browser interface? -3. What is a commit and what role does it play in the editing process? -4. Given a specific GitHub repository, can you determine the URL of the book website? +- Where are the contents of the book stored? +- How can you edit a single file via the GitHub browser interface? +- What is a commit and what role does it play in the editing process? +- Given a specific GitHub repository, can you determine the URL of the book website? +- How can you view the changes you made to the book? +- What is the purpose of a commit message and description? ``` \ No newline at end of file diff --git a/book/exercises/002.md b/book/exercises/002.md index 8e0c134..fe2bbcf 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -57,12 +57,13 @@ parts: 14. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) 15. Click `Commit changes` 16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) -17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). +17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{note} Check your understanding Before moving on to the next exercise, make sure you understand the following: -1. Are all files in the repository added to the website? -2. How many commits does it take to add a file online? -3. What needs to be on a page at least to be edit to the book? +- Are all files in the repository added to the website? +- How many commits does it take to add a file online? +- What needs to be on a page at least to be edit to the book? +- What is the purpose of the `_toc.yml` file? ``` \ No newline at end of file diff --git a/book/exercises/003.md b/book/exercises/003.md index d916416..8fe17c2 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -33,13 +33,13 @@ The 24th line of your `_config.yml` should look like 6. Add a message and description of your change 7. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) 8. Click `Commit changes` -9. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _config.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) -10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). +9. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _config.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` +10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{note} Check your understanding Before moving on to the next exercise, make sure you understand the following: -1. What is this special `_config.yml` file? -2. Changes in `_config.yml` can have effect on multiple pages in the book -3. The `_config.yml` is generally not used for adding content +- What is this special `_config.yml` file? +- Changes in `_config.yml` can have effect on multiple pages in the book +- The `_config.yml` is generally not used for adding content ``` \ No newline at end of file diff --git a/book/exercises/004.md b/book/exercises/004.md new file mode 100644 index 0000000..028d8fc --- /dev/null +++ b/book/exercises/004.md @@ -0,0 +1,25 @@ +# Exercise 4: _Your_ Version of the Book + +By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml`. But what if you want to make some changes but don't want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let's try and do that! Later on, you'll probably want to merge your newest version back into the original book. That's what we'll do in [](./005.md). + +Can you make a new `branch` of your book with an additional file `file_on_new_version.md` and view it online? + +1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com//`) - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice) +2. Add a title and description, eg. `Added some content` +3. On `Assignees`, click `Assign yourself +4. Click `Submit new issue` +5. In the new window, under `Development`, click `Create a branch` (note that you could also make branches in other ways, but in this way it's directly linked to the issue). A 'branch' is a separate version of the book which keeps the link with the original book. +6. Use the default options and click `Create branch` +7. Ignore the `checkout in your local repository`- popup for now (later on you'll know what this is and how to use it) +8. Go to `Code` - {octicon}`git-branch;1em` `main` and click on `1-` to open your branch. +9. Add a book page as explained in [](./002.md) and make sure you commit to the `1-`-branch. +10. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, you should now see multiple Branches. Click on the link of your new branch ``1-` +11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + +```{note} Check your understanding + +Before moving on to the next exercise, make sure you understand the following: +- What is the purpose of creating a new branch in your repository? +- Why is it good practice to create an issue before starting work on a new feature or change? +- How can you view the changes made in your new branch online? +``` \ No newline at end of file From dc4e7fbf5b33e4a020c23929193bc8b6e6192e62 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 16:48:50 +0100 Subject: [PATCH 13/21] fix formatting --- book/exercises/001.md | 5 +++-- book/exercises/002.md | 6 +++--- book/exercises/003.md | 9 +++++---- book/exercises/004.md | 3 ++- 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index 4191b53..2fc2ce7 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -10,10 +10,11 @@ Can you add some content to the intro page? 4. Add a message and description of your change. With this `commit` you save your changes to the git-timeline. Any commit can always be reverted. Therefore, it's useful to shortly explain what is included in your commit. Later on, you'll make commits which may contain changes to many different files. In that case, a descriptive commit message and description is even more useful! 5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) 6. Click `Commit changes`. -7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit messageof the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` +7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` 8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). -```{note} Check your understanding +```{admonition} Check your understanding +:class: note Before moving on to the next exercise, make sure you understand the following: - Where are the contents of the book stored? diff --git a/book/exercises/002.md b/book/exercises/002.md index fe2bbcf..db3a018 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -27,7 +27,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id diam non maur ````{admonition} Need some help? :class: tip, dropdown Your `_toc.yml` should look like -```yml +```yaml format: jb-book root: intro.md @@ -46,7 +46,6 @@ parts: - file: exercises/004.md - file: exercises/005.md - file: exercises/006.md - - file: exercises/007.md - file: references.md - file: changelog.md - file: credits.md @@ -59,7 +58,8 @@ parts: 16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) 17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -```{note} Check your understanding +```{admonition} Check your understanding +:class: note Before moving on to the next exercise, make sure you understand the following: - Are all files in the repository added to the website? diff --git a/book/exercises/003.md b/book/exercises/003.md index 8fe17c2..84e36d8 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -9,7 +9,7 @@ Can you edit the repository url defined in the `_config.yml`, change the title s ````{admonition} Need some help? :class: tip, dropdown The first line of your `_config.yml` should look like -```yml +```yaml author: , built with TeachBooks and Jupyter Book, CC BY 4.0 ``` ```` @@ -17,7 +17,7 @@ author: , built with TeachBooks a ````{admonition} Need some help? :class: tip, dropdown The 21st line of your `_config.yml` should look like -```yml +```yaml text: ``` ```` @@ -25,7 +25,7 @@ The 21st line of your `_config.yml` should look like ````{admonition} Need some help? :class: tip, dropdown The 24th line of your `_config.yml` should look like -```yml +```yaml repository_url: "https://github.com//" ``` ```` @@ -36,7 +36,8 @@ The 24th line of your `_config.yml` should look like 9. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _config.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` 10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -```{note} Check your understanding +```{admonition} Check your understanding +:class: note Before moving on to the next exercise, make sure you understand the following: - What is this special `_config.yml` file? diff --git a/book/exercises/004.md b/book/exercises/004.md index 028d8fc..fff7d37 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -16,7 +16,8 @@ Can you make a new `branch` of your book with an additional file `file_on_new_ve 10. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, you should now see multiple Branches. Click on the link of your new branch ``1-` 11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -```{note} Check your understanding +```{admonition} Check your understanding +:class: note Before moving on to the next exercise, make sure you understand the following: - What is the purpose of creating a new branch in your repository? From 23097075642eb53a408d6f654ee6ad7add9a30f2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:06:24 +0100 Subject: [PATCH 14/21] Changed two to existing file --- book/exercises/002.md | 44 +++++++++++---------------------- book/exercises/004.md | 2 +- book/file_to_be_added_to_toc.md | 2 ++ 3 files changed, 17 insertions(+), 31 deletions(-) create mode 100644 book/file_to_be_added_to_toc.md diff --git a/book/exercises/002.md b/book/exercises/002.md index db3a018..019ff30 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -1,28 +1,12 @@ # Exercise 2: Add a new file to the table of contents -Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's create a new file and add it to that list! +Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet! -Can you create a file named `my_first_file.md` and add it successfully to the book? +Add the file named `file_to_be_added_to_toc.md` and add it successfully to the book? -1. Go to the `/book` directory of your GitHub repository and add a file (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - `Add file` - {octicon}`plus;1em` `Create new file` -2. Name your file `my_first_file.md`. Don't forget the `.md`! -3. In the `Edit` field, start the first line with the header of your page (each file needs to have a header which will be the title shown in the table of contents): -```md -# Title of my first file -``` -4. On a new line, add some more text so that you end up with something like: - -```md -# Title of my first file -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id diam non mauris auctor sollicitudin. Ut quis nunc lobortis, iaculis massa id, eleifend justo. Nulla ac auctor sapien. Etiam sit amet est a ex vestibulum porta. Nulla non lacus a purus luctus blandit sit amet non nibh. Curabitur vitae cursus dolor. Ut eu nisi nec enim ullamcorper fermentum. -``` -5. Want to view all the text without horizontal scrolling? Click `No wrap` and select `Soft wrap` -6. Click `Commit changes` -7. Add a message and description of your change -8. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) -9. Click `Commit changes` -10. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` -11. Add this file as a second item in the `Some content` chapter +1. Go to the (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` directory of your GitHub repository and find the location of `file_to_be_added_to_toc.md` +2. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` +3. Add `file_to_be_added_to_toc.md` as a second item in the `Some content` chapter ````{admonition} Need some help? :class: tip, dropdown @@ -37,7 +21,7 @@ parts: - file: some_content/overview.md sections: - file: some_content/text_and_code.ipynb - - file: my_first_file.md + - file: file_to_be_added_to_toc.md - file: exercises/exercises sections: - file: exercises/001.md @@ -51,19 +35,19 @@ parts: - file: credits.md ``` ```` -12. Click `Commit changes` -13. Add a message and description of your change -14. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) -15. Click `Commit changes` -16. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) -17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +4. Click `Commit changes` +5. Add a message and description of your change +6. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) +7. Click `Commit changes` +8. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) +9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding :class: note Before moving on to the next exercise, make sure you understand the following: - Are all files in the repository added to the website? -- How many commits does it take to add a file online? -- What needs to be on a page at least to be edit to the book? - What is the purpose of the `_toc.yml` file? +- What happens if a file is not listed in the `_toc.yml`? +- How can you verify that your changes to `_toc.yml` were successful? ``` \ No newline at end of file diff --git a/book/exercises/004.md b/book/exercises/004.md index fff7d37..1058d1e 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -4,7 +4,7 @@ By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml Can you make a new `branch` of your book with an additional file `file_on_new_version.md` and view it online? -1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com//`) - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice) +1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com//`) - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice so that people know where you're working on) 2. Add a title and description, eg. `Added some content` 3. On `Assignees`, click `Assign yourself 4. Click `Submit new issue` diff --git a/book/file_to_be_added_to_toc.md b/book/file_to_be_added_to_toc.md new file mode 100644 index 0000000..bfdbd52 --- /dev/null +++ b/book/file_to_be_added_to_toc.md @@ -0,0 +1,2 @@ +# Title of the file to be added to the toc +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id diam non mauris auctor sollicitudin. Ut quis nunc lobortis, iaculis massa id, eleifend justo. Nulla ac auctor sapien. Etiam sit amet est a ex vestibulum porta. Nulla non lacus a purus luctus blandit sit amet non nibh. Curabitur vitae cursus dolor. Ut eu nisi nec enim ullamcorper fermentum. \ No newline at end of file From 5955e3fdd1ae527aa10aa99f2fe1d30cc3151c4e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:09:44 +0100 Subject: [PATCH 15/21] Update 002.md --- book/exercises/002.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/exercises/002.md b/book/exercises/002.md index 019ff30..42d7d50 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -50,4 +50,5 @@ Before moving on to the next exercise, make sure you understand the following: - What is the purpose of the `_toc.yml` file? - What happens if a file is not listed in the `_toc.yml`? - How can you verify that your changes to `_toc.yml` were successful? +- Does the structure of the `_toc.yml` file need to match the directory structure of the repository? ``` \ No newline at end of file From d83403624e912f3b6bd4c388f5693640d20227af Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:14:32 +0100 Subject: [PATCH 16/21] Update 002.md --- book/exercises/002.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/exercises/002.md b/book/exercises/002.md index 42d7d50..c2ab6ad 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -2,7 +2,7 @@ Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet! -Add the file named `file_to_be_added_to_toc.md` and add it successfully to the book? +Add the file named `file_to_be_added_to_toc.md` to the book? 1. Go to the (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` directory of your GitHub repository and find the location of `file_to_be_added_to_toc.md` 2. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` From a7b71c813ce370ac9e146a43677ed61dbd4476de Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:16:32 +0100 Subject: [PATCH 17/21] WIP --- book/exercises/002.md | 2 +- book/exercises/004.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/002.md b/book/exercises/002.md index c2ab6ad..271d0db 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -2,7 +2,7 @@ Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet! -Add the file named `file_to_be_added_to_toc.md` to the book? +Can you add the file named `file_to_be_added_to_toc.md` to the book website? 1. Go to the (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` directory of your GitHub repository and find the location of `file_to_be_added_to_toc.md` 2. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` diff --git a/book/exercises/004.md b/book/exercises/004.md index 1058d1e..97dd68c 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -2,7 +2,7 @@ By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml`. But what if you want to make some changes but don't want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let's try and do that! Later on, you'll probably want to merge your newest version back into the original book. That's what we'll do in [](./005.md). -Can you make a new `branch` of your book with an additional file `file_on_new_version.md` and view it online? +Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? 1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com//`) - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice so that people know where you're working on) 2. Add a title and description, eg. `Added some content` From a180e5ab3a2111edbc5a0144821c03c511b1bc96 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:36:56 +0100 Subject: [PATCH 18/21] Added exercise 5 --- book/exercises/001.md | 2 +- book/exercises/002.md | 2 +- book/exercises/003.md | 2 +- book/exercises/004.md | 4 ++-- book/exercises/005.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 33 insertions(+), 5 deletions(-) create mode 100644 book/exercises/005.md diff --git a/book/exercises/001.md b/book/exercises/001.md index 2fc2ce7..eb58f9d 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -2,7 +2,7 @@ Let's start with the most basic edit: add some text to a file and see that the website is updated. -Can you add some content to the intro page? +> Can you add some content to the intro page? 1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` 2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! diff --git a/book/exercises/002.md b/book/exercises/002.md index 271d0db..46ee523 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -2,7 +2,7 @@ Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet! -Can you add the file named `file_to_be_added_to_toc.md` to the book website? +> Can you add the file named `file_to_be_added_to_toc.md` to the book website? 1. Go to the (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` directory of your GitHub repository and find the location of `file_to_be_added_to_toc.md` 2. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` diff --git a/book/exercises/003.md b/book/exercises/003.md index 84e36d8..dd39b96 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -2,7 +2,7 @@ As we've added some content by now, let's make this book a bit more personal! We'll make some changes to the `_config.yml` file which changes the configuration of the book website. -Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? +> Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? 1. Go to the the file `book/_config.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_config.yml` - {octicon}`pencil;1em` `Edit this file` 2. In the `Edit` field, change the author which will be shown in the footer of the book website. diff --git a/book/exercises/004.md b/book/exercises/004.md index 97dd68c..05d8ec3 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -2,11 +2,11 @@ By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml`. But what if you want to make some changes but don't want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let's try and do that! Later on, you'll probably want to merge your newest version back into the original book. That's what we'll do in [](./005.md). -Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? +> Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? 1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com//`) - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice so that people know where you're working on) 2. Add a title and description, eg. `Added some content` -3. On `Assignees`, click `Assign yourself +3. On `Assignees`, click `Assign yourself` to make clear that you feel responsible for this issue. 4. Click `Submit new issue` 5. In the new window, under `Development`, click `Create a branch` (note that you could also make branches in other ways, but in this way it's directly linked to the issue). A 'branch' is a separate version of the book which keeps the link with the original book. 6. Use the default options and click `Create branch` diff --git a/book/exercises/005.md b/book/exercises/005.md new file mode 100644 index 0000000..40c8375 --- /dev/null +++ b/book/exercises/005.md @@ -0,0 +1,28 @@ +# Exercise 5: Merge your version in the original book + +In [](./004.md) you created your own version of a book. But it would be a pity if you never contribute back to the original book right? Probably your additions are very useful there too! You'll merge you version of the book which is stored on a branch into the original book which is on main. If there've been some changes on that main branch in the meantime, git will take care of that! + +> Can you merge your branch into `main` with a pull request? + +1. Go to your repository homepage (`https://github.com//`). Probably, it will have big yellow announcement saying {octicon}`git-branch;1em` `1- had recent pushes minutes ago - Compare & Pull request`. We'll ignore that for now and do it manually. +2. Go to the pull request page on your repository homepage (`https://github.com//`) - {octicon}`git-pull-request;1em` and click `New pull request` +3. On {octicon}`git-compare;1em` make sure you point from your branch `1-` into `main`. So, `main` on the left, {octicon}`arrow-left;1em` and `1-` on the right. Main is the default name for the branch which has the most recent/stable version. The page should now show all the changes you made on the `1-`-branch. If there would be changes on the `main` branch in the meantime, they should show up here too. +4. Click `Create pull request` to start the process of moving your changes into the `main` branch. If there were changes on both branches which are conflicting, it will tell you there's a merge conflict. If you followed the steps until now, that shouldn't be the case. Solving those merge conflicts is topic for another exercise. +5. Add a title and description described the changes you made. This is done to give other people a summary of what has been changed. +6. Assign yourself to make clear that you feel responsible. +7. Click `Create pull request`. On the next page you'll see that GitHub gives an announcement {octicon}`bookmark;1em` ` linked an issue now that may be closed by this pull request`. That sounds useful! +8. As you're the only one in this repo there's nobody to review your work. So let's continue and merge your changes into `main` by clicking `Merge pull request` and `Confirm merge` (eventually specifying the suggested commit message and description) +9. As this issue is now closed, you can safely remove the branch `1-` as you don't need it anymore. You can do so by clicking `Delete branch`. +10. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Merge pull request #2 from /1- / the commit message of the commit you just made` - Wait for it to finish - In the summary, click the link of the main branch or the primary book at root. +11. Do you see your change from your branch 1-? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Check that the url indeed shows that you're on main. + +```{admonition} Check your understanding +:class: note + +Before moving on to the next exercise, make sure you understand the following: +- What is the purpose of creating a pull request? +- How do you manually create a pull request on GitHub? +- Why is it important to add a title and description to your pull request? +- What is the final step after merging your pull request? +- How can you verify that your changes have been successfully merged into the main branch? +``` \ No newline at end of file From b33a7ae010d2308b9ad5a0590c91a2afc68845e0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:38:08 +0100 Subject: [PATCH 19/21] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index 8e6ddf2..f1f35d6 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -13,6 +13,7 @@ parts: - file: exercises/002.md - file: exercises/003.md - file: exercises/004.md + - file: exercises/005.md - file: references.md - file: changelog.md - file: credits.md From 3aa2059f0a43cda9114c1b7fabab155e7a7d9a3c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 18:05:31 +0100 Subject: [PATCH 20/21] Added exercise 6 --- README.md | 2 +- book/_toc.yml | 1 + book/exercises/005.md | 2 +- book/exercises/006.md | 29 +++++++++++++++++++++++++++++ 4 files changed, 32 insertions(+), 2 deletions(-) create mode 100644 book/exercises/006.md diff --git a/README.md b/README.md index de47695..72c8f28 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Video available [here](https://youtu.be/nN3Oi_MVvF0) ![Create new repository](figures/create_new_repository.png) -3. You can choose for `Private` only if you've GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server. Otherwise, you won't be able to publish your TeachBook online. +3. You can choose for `Private` only if you've GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server. Otherwise, you won't be able to publish your TeachBook online. Furthermore, it prevents people from contributing to your book, making your book essentially 'closed' instead of 'open. 4. (Only required for private repositories:) Create a Personal Access Token (classic) with at least the scopes `repo`, `read:org` and `gist` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` (`Settings` > `Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`). diff --git a/book/_toc.yml b/book/_toc.yml index f1f35d6..10f519a 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -14,6 +14,7 @@ parts: - file: exercises/003.md - file: exercises/004.md - file: exercises/005.md + - file: exercises/006.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/005.md b/book/exercises/005.md index 40c8375..31f5d0c 100644 --- a/book/exercises/005.md +++ b/book/exercises/005.md @@ -6,7 +6,7 @@ In [](./004.md) you created your own version of a book. But it would be a pity i 1. Go to your repository homepage (`https://github.com//`). Probably, it will have big yellow announcement saying {octicon}`git-branch;1em` `1- had recent pushes minutes ago - Compare & Pull request`. We'll ignore that for now and do it manually. 2. Go to the pull request page on your repository homepage (`https://github.com//`) - {octicon}`git-pull-request;1em` and click `New pull request` -3. On {octicon}`git-compare;1em` make sure you point from your branch `1-` into `main`. So, `main` on the left, {octicon}`arrow-left;1em` and `1-` on the right. Main is the default name for the branch which has the most recent/stable version. The page should now show all the changes you made on the `1-`-branch. If there would be changes on the `main` branch in the meantime, they should show up here too. +3. On {octicon}`git-compare;1em` make sure you point from your branch `1-` into `main`. So, `main` on the left, {octicon}`arrow-left;1em`, and `1-` on the right. Main is the default name for the branch which has the most recent/stable version. The page should now show all the changes you made on the `1-`-branch. If there would be changes on the `main` branch in the meantime, they should show up here too. 4. Click `Create pull request` to start the process of moving your changes into the `main` branch. If there were changes on both branches which are conflicting, it will tell you there's a merge conflict. If you followed the steps until now, that shouldn't be the case. Solving those merge conflicts is topic for another exercise. 5. Add a title and description described the changes you made. This is done to give other people a summary of what has been changed. 6. Assign yourself to make clear that you feel responsible. diff --git a/book/exercises/006.md b/book/exercises/006.md new file mode 100644 index 0000000..a73b7b5 --- /dev/null +++ b/book/exercises/006.md @@ -0,0 +1,29 @@ +# Exercise 6: Contribute to the book of somebody else + +So far you did everything on your own. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using git! Therefore, you'll take the book of someone else and create your own version of that one. Unlike before, we cannot simply make a branch, because you don't have access to their repository. However, you can make a copy of the repository on your own account, which is called a fork. Let's use that and contribute back to your friend's repository at the end. + +> Can you fork a book repository of someone else, make changes and contribute back? + +1. Go to the repository you want to contribute to (`https://github.com//`) and add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository you want to contribute to (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` +4. Make some changes on the main branch of your forked repo. +5. Check the changes in the online book. +6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. +7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. +8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. +9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. +10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! + +#### ROBERT, CAN YOU CONTINUE HERE? + +```{admonition} Check your understanding +:class: note + +Before moving on to the next exercise, make sure you understand the following: +- What is a fork and how does it differ from a branch? +- Why is it important to create an issue before starting to work on a contribution? +- How do you create a pull request from a forked repository to the original repository? +- What should you include in the description of a pull request? +- How can you ensure that your friend is aware of your pull request? +``` \ No newline at end of file From e155455512514c2aa5da2020ab135e7ec9993f96 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Fri, 13 Dec 2024 20:36:05 +0100 Subject: [PATCH 21/21] Excercise 6 --- book/exercises/006.md | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/book/exercises/006.md b/book/exercises/006.md index a73b7b5..a256af5 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -1,13 +1,25 @@ # Exercise 6: Contribute to the book of somebody else -So far you did everything on your own. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using git! Therefore, you'll take the book of someone else and create your own version of that one. Unlike before, we cannot simply make a branch, because you don't have access to their repository. However, you can make a copy of the repository on your own account, which is called a fork. Let's use that and contribute back to your friend's repository at the end. +```{tip} +For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. +``` + +So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. + +```{note} +The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. +``` > Can you fork a book repository of someone else, make changes and contribute back? -1. Go to the repository you want to contribute to (`https://github.com//`) and add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). -2. Go back to the home page of repository you want to contribute to (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +```{tip} +This part describes how you can make a change in the book of someone else. +``` + +1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. 3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` -4. Make some changes on the main branch of your forked repo. +4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ 5. Check the changes in the online book. 6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. 7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. @@ -15,12 +27,22 @@ So far you did everything on your own. However, book-editing would be really bor 9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. 10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! -#### ROBERT, CAN YOU CONTINUE HERE? +```{tip} +This part describes how you can accept the changes in your book made by someone else. +``` + +1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. +2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? +3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. +4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. +5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. + +Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. ```{admonition} Check your understanding :class: note -Before moving on to the next exercise, make sure you understand the following: +Before moving on, make sure you understand the following: - What is a fork and how does it differ from a branch? - Why is it important to create an issue before starting to work on a contribution? - How do you create a pull request from a forked repository to the original repository?