From c7119a7826e85e6afae8b0830c537afb1c310d6d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 28 Jan 2025 15:57:06 +0100 Subject: [PATCH 01/54] add with caption --- book/exercises/001.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index 49a8240..af92980 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -15,13 +15,19 @@ 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 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!). -```{hint} Watch the steps in action below +````{hint} Watch the steps in action below :class: dropdown -![First file edit guide](https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true) -[Or watch the video here](https://youtu.be/gn1zBmmunco) +```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true +--- +name: template_demo_public +--- +Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco) ``` + +```` + :::{card} Check your understanding ::: From 2e56c7b03abd9c0b937853b7cba8c496aa8913e0 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Sun, 16 Feb 2025 11:08:41 +0100 Subject: [PATCH 02/54] change toc --- book/_toc.yml | 10 ++++++++++ book/exercises/007.md | 0 2 files changed, 10 insertions(+) create mode 100644 book/exercises/007.md diff --git a/book/_toc.yml b/book/_toc.yml index bcbd396..c3d339d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -8,6 +8,7 @@ parts: sections: - file: some_content/text_and_code.ipynb - file: exercises + caption: Beginner exercises sections: - file: exercises/001.md - file: exercises/002.md @@ -16,6 +17,15 @@ parts: - file: exercises/005.md - file: exercises/006.md - file: exercises/summary + - file: advances_exercises.md + caption: Advanced exercises + sections: + - file: user_type_3.md + sections: + - file: exercises/007.md +# - file: exercises/... +# - file: user_type_4.md +# etc. - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/007.md b/book/exercises/007.md new file mode 100644 index 0000000..e69de29 From 219a587a031df2e3192c9505a1b757d1966aba22 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Sun, 16 Feb 2025 19:03:43 +0100 Subject: [PATCH 03/54] exercise add content --- book/exercises/007.md | 24 ++++++++++++++++++++++++ book/exercises/008.md | 0 2 files changed, 24 insertions(+) create mode 100644 book/exercises/008.md diff --git a/book/exercises/007.md b/book/exercises/007.md index e69de29..8c575d4 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -0,0 +1,24 @@ +# Exercise 6: Add your first content (File Structure) + +Now that you've made your own version of the book, it's time to add some content. + +1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. + +2. Let's create the structure of your chapter. You can start by adding a title to the section. The title is always defined in the first line of the file after the hashtag `#`. Then yo can also add sections and subsections as needed. + +``` +# Chapter Title (H1) +## Section Title (H2) +### Subsection Title (H3) +#### Smaller Heading (H4) +``` + +3. Add some text to the sections. + +4. When you are ready, commit your changes to the remote repository by clicking on the green `Commit changes` button. + +5. Add a commit message. + +6. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting (user type 4)) + +7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. diff --git a/book/exercises/008.md b/book/exercises/008.md new file mode 100644 index 0000000..e69de29 From a4100c482832c4008971e6809e76275e9bb4e7bd Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 20 Feb 2025 12:49:16 +0100 Subject: [PATCH 04/54] Update requirements.txt --- requirements.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/requirements.txt b/requirements.txt index 4d6bb6c..254927d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,3 +9,6 @@ teachbooks-sphinx-tippy # now list the packages (and the respective url) you wish to download from the GitLab package registry --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple sphinx-thebe ~= 0.9.9 + +# Now list the files you want to download directly from GitHub +git+https://github.com/TeachBooks/sphinx-iframes.git From e7a0808bb25fb3741219b23998a9b72da47c285f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 20 Feb 2025 12:50:31 +0100 Subject: [PATCH 05/54] Update 001.md --- book/exercises/001.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index af92980..eb7ce52 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -28,10 +28,12 @@ Demonstration of all steps of this exercise, video available [here](https://yout ```` -:::{card} Check your understanding - -::: +::::{card} Check your understanding +```{h5p} https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=2 +``` +:::: -:::{card} Check your understanding - -::: \ No newline at end of file +::::{card} Check your understanding +```{h5p} https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=1 +``` +:::: From 22128a622fdf68cb51f0f05dae1a8bc16d43f9b3 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 20 Feb 2025 12:55:44 +0100 Subject: [PATCH 06/54] Update _config.yml --- book/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_config.yml b/book/_config.yml index 6ad58d4..d488258 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -43,6 +43,7 @@ sphinx: - download_link_replacer - sphinx.ext.extlinks - sphinx_image_inverter + - sphinx_iframes - sphinx_exercise - teachbooks_sphinx_tippy From 17b93d18c9c1bcabaa4a1cbf427f816ab7804615 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Feb 2025 10:38:21 +0100 Subject: [PATCH 07/54] Update changelog.md --- book/changelog.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/changelog.md b/book/changelog.md index 729bf67..77c7c70 100644 --- a/book/changelog.md +++ b/book/changelog.md @@ -1,4 +1,6 @@ # Changelog -## `` [``](<`link to release on GitHub>`) +## ``: `` - `` [](``) +- ... +- Full Changelog: `[...]()' From 82654c6ffda8a333504b9a5f2a9e38020e4ff661 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Feb 2025 10:39:42 +0100 Subject: [PATCH 08/54] Update changelog.md --- book/changelog.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/book/changelog.md b/book/changelog.md index 77c7c70..23465d6 100644 --- a/book/changelog.md +++ b/book/changelog.md @@ -1,6 +1,11 @@ # Changelog -## ``: `` +## ``: `` - `` [](``) - ... - Full Changelog: `[...]()' + +## ``: <...> +- <...> + +<...> From e22ec7dcf017701757736536521e84c3b9b3816a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 23 Feb 2025 19:29:00 +0100 Subject: [PATCH 09/54] Update requirements.txt --- requirements.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/requirements.txt b/requirements.txt index 254927d..0a7c41c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,9 +6,6 @@ download_link_replacer sphinx-exercise teachbooks-sphinx-tippy -# now list the packages (and the respective url) you wish to download from the GitLab package registry ---extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple -sphinx-thebe ~= 0.9.9 - # Now list the files you want to download directly from GitHub +git+https://github.com/TeachBooks/Sphinx-Thebe git+https://github.com/TeachBooks/sphinx-iframes.git From faba4e7898a6acb5681e5e9416255e33b6a0f949 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 23 Feb 2025 19:34:18 +0100 Subject: [PATCH 10/54] Update requirements.txt --- requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 0a7c41c..3c3ee06 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,7 +5,7 @@ sphinx-image-inverter download_link_replacer sphinx-exercise teachbooks-sphinx-tippy +sphinx-iframes -# Now list the files you want to download directly from GitHub +# Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe -git+https://github.com/TeachBooks/sphinx-iframes.git From f88cac7733a54e1170b31e0b5676e55ea7ffd81c Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 14:59:54 +0100 Subject: [PATCH 11/54] fix toc --- book/_toc.yml | 2 -- book/exercises/008.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index c3d339d..70ae5bb 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -8,7 +8,6 @@ parts: sections: - file: some_content/text_and_code.ipynb - file: exercises - caption: Beginner exercises sections: - file: exercises/001.md - file: exercises/002.md @@ -18,7 +17,6 @@ parts: - file: exercises/006.md - file: exercises/summary - file: advances_exercises.md - caption: Advanced exercises sections: - file: user_type_3.md sections: diff --git a/book/exercises/008.md b/book/exercises/008.md index e69de29..3a7e816 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -0,0 +1,29 @@ +# Exercise 8: Add a figure/gif/video + +Now let's add a figure. If you want to add a figure/gif/video to you book, you can refer to another website. This is quite handy for video's but it does carry the risk that this figure/gif/video will no longer be visible if the location is changed. + + + + + +So it is better to add the source directly to the book. So you first need to upload a figure to GitHub and then reference that figure in our file. (Note: later this becomes much easier). + + +```{figure} figures/HubUser3_EditFile2.PNG +--- +width: 80% +align: center +--- +Commit changes +``` + +6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as with markdown `(file.md)` files. + +```{figure} figures/HubUser3_toc.PNG +--- +width: 80% +align: center +--- +Table of contents +``` +```` \ No newline at end of file From 9d80144dcb783b2764720194d18ca13e20959974 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 15:11:36 +0100 Subject: [PATCH 12/54] new files --- book/_toc.yml | 10 ++++------ book/exercises/advanced_exercises.md | 0 book/{ => exercises}/exercises.md | 0 book/exercises/type3.md | 0 4 files changed, 4 insertions(+), 6 deletions(-) create mode 100644 book/exercises/advanced_exercises.md rename book/{ => exercises}/exercises.md (100%) create mode 100644 book/exercises/type3.md diff --git a/book/_toc.yml b/book/_toc.yml index 70ae5bb..d2184e2 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -7,7 +7,7 @@ parts: - file: some_content/overview.md sections: - file: some_content/text_and_code.ipynb - - file: exercises + - file: exercises/exercises.md sections: - file: exercises/001.md - file: exercises/002.md @@ -16,14 +16,12 @@ parts: - file: exercises/005.md - file: exercises/006.md - file: exercises/summary - - file: advances_exercises.md + - file: exercises/advanced_exercises.md sections: - - file: user_type_3.md + - file: type3.md sections: - file: exercises/007.md -# - file: exercises/... -# - file: user_type_4.md -# etc. + - file: exercises/008.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/advanced_exercises.md b/book/exercises/advanced_exercises.md new file mode 100644 index 0000000..e69de29 diff --git a/book/exercises.md b/book/exercises/exercises.md similarity index 100% rename from book/exercises.md rename to book/exercises/exercises.md diff --git a/book/exercises/type3.md b/book/exercises/type3.md new file mode 100644 index 0000000..e69de29 From 1cb8a2cd8efa9cf8ddb3c814b09de758cf980aa2 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 15:15:59 +0100 Subject: [PATCH 13/54] ? --- book/exercises/advanced_exercises.md | 5 +++++ book/exercises/type3.md | 1 + 2 files changed, 6 insertions(+) diff --git a/book/exercises/advanced_exercises.md b/book/exercises/advanced_exercises.md index e69de29..e56629f 100644 --- a/book/exercises/advanced_exercises.md +++ b/book/exercises/advanced_exercises.md @@ -0,0 +1,5 @@ +# Advanced exercises + +The previous exercise guide you through making your own book. Now lets get specific! + +This chapter includes a couple of more exercises directed to the different user types. \ No newline at end of file diff --git a/book/exercises/type3.md b/book/exercises/type3.md index e69de29..0c64beb 100644 --- a/book/exercises/type3.md +++ b/book/exercises/type3.md @@ -0,0 +1 @@ +# User Type 3 \ No newline at end of file From 1199aa6c4227a49e2c8ac09b9c525364882fd8b8 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 15:20:21 +0100 Subject: [PATCH 14/54] more files --- book/_toc.yml | 5 ++++- book/exercises/type4.md | 0 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 book/exercises/type4.md diff --git a/book/_toc.yml b/book/_toc.yml index d2184e2..f5ebf5d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -18,10 +18,13 @@ parts: - file: exercises/summary - file: exercises/advanced_exercises.md sections: - - file: type3.md + - file: exercises/type3.md sections: - file: exercises/007.md - file: exercises/008.md + - file: exercises/type4.mb + sections: + - file: exercises/009.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/type4.md b/book/exercises/type4.md new file mode 100644 index 0000000..e69de29 From 0777dd2942ed4630a9b881b14c605c31823cb1fe Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 15:21:50 +0100 Subject: [PATCH 15/54] Update type4.md --- book/exercises/type4.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/exercises/type4.md b/book/exercises/type4.md index e69de29..51b1490 100644 --- a/book/exercises/type4.md +++ b/book/exercises/type4.md @@ -0,0 +1 @@ +# User type 4 \ No newline at end of file From 4e3cb2a017a874e12b85754060af59e65aea2064 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 15:23:28 +0100 Subject: [PATCH 16/54] Create 009.md --- book/exercises/009.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 book/exercises/009.md diff --git a/book/exercises/009.md b/book/exercises/009.md new file mode 100644 index 0000000..36da758 --- /dev/null +++ b/book/exercises/009.md @@ -0,0 +1,2 @@ +# Ninth exercises +kdjb \ No newline at end of file From 0c4af84481b6ed279c9daaf488c0b055fc12eceb Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 24 Feb 2025 16:12:52 +0100 Subject: [PATCH 17/54] updates --- book/exercises/001.md | 1 + book/exercises/007.md | 20 ++++++++++++++------ book/exercises/009.md | 36 ++++++++++++++++++++++++++++++++++-- book/exercises/summary.md | 11 ++++++++--- book/exercises/type3.md | 10 +++++++++- book/exercises/type4.md | 5 ++++- 6 files changed, 70 insertions(+), 13 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index af92980..5e56d75 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -1,3 +1,4 @@ +(exercise_1)= # 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. diff --git a/book/exercises/007.md b/book/exercises/007.md index 8c575d4..4257764 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -1,16 +1,24 @@ -# Exercise 6: Add your first content (File Structure) +# Exercise 6: File Structure (Markdown) -Now that you've made your own version of the book, it's time to add some content. +In this exercise you will add the structure to your chapters. + +```{tip} + +More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). + +``` 1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. 2. Let's create the structure of your chapter. You can start by adding a title to the section. The title is always defined in the first line of the file after the hashtag `#`. Then yo can also add sections and subsections as needed. ``` -# Chapter Title (H1) -## Section Title (H2) -### Subsection Title (H3) -#### Smaller Heading (H4) +# Chapter Title +## Section Title +### Subsection Title +#### Smaller Heading +##### Heading level 5 +###### Heading level 6 ``` 3. Add some text to the sections. diff --git a/book/exercises/009.md b/book/exercises/009.md index 36da758..a49a9c9 100644 --- a/book/exercises/009.md +++ b/book/exercises/009.md @@ -1,2 +1,34 @@ -# Ninth exercises -kdjb \ No newline at end of file +# Exercise 9: Referencing using target headers + +It can be really useful to refer to a specific section in your book while working in a different file. Referencing can be done using target headers. ()= + +1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. + +2. Identify the section you want to reference and name it ebtween bracketsfor example exercise_1. + +``` +(exercise_1)= +# 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... + +``` + +3. Referncing + +There are three types of referencing + +If you want to refernce in line you can use: + +My favourte exercise was {ref}`exercise_1`. + +``` +My favourte exercise was {ref}`exercise_1`. +``` +You can specify the text of the target: + +{ref}`MyST syntax lecture <exercise_1>` + +Another alternative is to use Markdown syntax: + +[MyST syntax lecture](exercise_1) \ No newline at end of file diff --git a/book/exercises/summary.md b/book/exercises/summary.md index 866137e..25bc7d6 100644 --- a/book/exercises/summary.md +++ b/book/exercises/summary.md @@ -1,6 +1,6 @@ # Summary of exercises: All Exercises -With the exercises, you did all the steps of our TeachBooks workflow! +With the simple exercises, you did all the steps of our TeachBooks workflow! ```{figure} https://github.com/TeachBooks/logos_and_visualisations/blob/main/TB_flowchart/TeachBooks_flowchart.svg?raw=true --- @@ -9,7 +9,7 @@ align: center --- ``` -Here is how the exercises relate to the workflow. +Here is how these exercises relate to the workflow. | Step No. | Name | Exercise | Description | | :---: | :---: | :---: | :---: | @@ -18,4 +18,9 @@ Here is how the exercises relate to the workflow. | 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | | 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary | | 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| -| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks | \ No newline at end of file +| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks | + +## Keep practicing + +For additional practice, there are more exercises relating to the capacities of each user type. +Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are! \ No newline at end of file diff --git a/book/exercises/type3.md b/book/exercises/type3.md index 0c64beb..7c67e14 100644 --- a/book/exercises/type3.md +++ b/book/exercises/type3.md @@ -1 +1,9 @@ -# User Type 3 \ No newline at end of file +# User Type 3 + +Now that you've made your own version of the book, it's time to add some content. As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while ipynb` files contain both text and executable code cells. In this exercise you will learn how to structure a `.md` file. + +Exercises for user type 3 relate to: + +- File Structure (Markdown) +- In-text referencing +- Adding a figure \ No newline at end of file diff --git a/book/exercises/type4.md b/book/exercises/type4.md index 51b1490..59eaaa7 100644 --- a/book/exercises/type4.md +++ b/book/exercises/type4.md @@ -1 +1,4 @@ -# User type 4 \ No newline at end of file +# User type 4 + + +User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). Using this skills, this user type can take the role as editor, managing more than just book content. \ No newline at end of file From fd0e1a131f42591e1f749dc0ed63d96a31efb830 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 24 Feb 2025 17:53:06 +0100 Subject: [PATCH 18/54] works? --- book/exercises/007.md | 10 ++++----- book/exercises/008.md | 48 +++++++++++++++++++++++++++++++------------ 2 files changed, 40 insertions(+), 18 deletions(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index 4257764..745a2a0 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -1,6 +1,6 @@ -# Exercise 6: File Structure (Markdown) +# Exercise 7: File Structure (Markdown) -In this exercise you will add the structure to your chapters. +In this exercise you will learn how to structure your chapters. ```{tip} @@ -10,7 +10,7 @@ More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyt 1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. -2. Let's create the structure of your chapter. You can start by adding a title to the section. The title is always defined in the first line of the file after the hashtag `#`. Then yo can also add sections and subsections as needed. +2. Let's create the structure of your chapter. You can start by adding a title to the section. The title is always defined in the first line of the file after the hashtag `#`. Then you can also add sections and subsections as needed. ``` # Chapter Title @@ -21,9 +21,9 @@ More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyt ###### Heading level 6 ``` -3. Add some text to the sections. +3. Add some text to the (sub)sections to complete your chapter. -4. When you are ready, commit your changes to the remote repository by clicking on the green `Commit changes` button. +4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. 5. Add a commit message. diff --git a/book/exercises/008.md b/book/exercises/008.md index 3a7e816..d60f9d2 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -1,29 +1,51 @@ -# Exercise 8: Add a figure/gif/video +# Exercise 8: Add visual media -Now let's add a figure. If you want to add a figure/gif/video to you book, you can refer to another website. This is quite handy for video's but it does carry the risk that this figure/gif/video will no longer be visible if the location is changed. +To help you illustrate your content, it can be sueful to add some type of visual media such as figures, videos or gifs. If you want to add a figure/gif/video to you book, you can refer to another website. This is quite handy for video's but it does carry the risk that this figure/gif/video will no longer be visible if the location is changed. So it is better to add the source directly to the book. +````{tab-set} +```{tab-item} Linking +Hello +``` +```{tab-item} Embedding +1. You will first need to upload your media to the repository. Navigate to the folder called figures(`book/figures`) and make sure you are i the right branch. On the right top, click on `Add file` and `Upload new file`. -So it is better to add the source directly to the book. So you first need to upload a figure to GitHub and then reference that figure in our file. (Note: later this becomes much easier). +2. Choose the visual media you want to upload. Remember its file name as you will need it later. +3. Commit your changes. -```{figure} figures/HubUser3_EditFile2.PNG +4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. + +5. Copy this syntax + +```md + +```{figure} figures/<new_figure>.PNG --- width: 80% align: center +name: my_new_figure --- -Commit changes +New figure + +``` ``` -6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as with markdown `(file.md)` files. +```{Warning} -```{figure} figures/HubUser3_toc.PNG ---- -width: 80% -align: center ---- -Table of contents +Make sure the file extension of your figure is correct because markdown differentiates capital letters! ``` -```` \ No newline at end of file + +6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +7. Add a commit message. + +8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting (user type 4)) + +9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + +``` +```` + From cbdc2afeb21fb236be771c7ff6e67ce09425f176 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 24 Feb 2025 18:01:01 +0100 Subject: [PATCH 19/54] now? --- book/exercises/008.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index d60f9d2..3d2bc48 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -2,13 +2,13 @@ To help you illustrate your content, it can be sueful to add some type of visual media such as figures, videos or gifs. If you want to add a figure/gif/video to you book, you can refer to another website. This is quite handy for video's but it does carry the risk that this figure/gif/video will no longer be visible if the location is changed. So it is better to add the source directly to the book. -````{tab-set} -```{tab-item} Linking +`````{tab-set} +````{tab-item} Linking Hello -``` -```{tab-item} Embedding +```` +````{tab-item} Embedding 1. You will first need to upload your media to the repository. Navigate to the folder called figures(`book/figures`) and make sure you are i the right branch. On the right top, click on `Add file` and `Upload new file`. @@ -20,7 +20,7 @@ Hello 5. Copy this syntax -```md +```python ```{figure} figures/<new_figure>.PNG --- @@ -46,6 +46,6 @@ Make sure the file extension of your figure is correct because markdown differen 9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -``` ```` +````` From 5062f449efbc0a110b557cfbcfc6f36e5fb16492 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 24 Feb 2025 18:09:49 +0100 Subject: [PATCH 20/54] update --- book/exercises/008.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index 3d2bc48..ce31697 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -10,7 +10,7 @@ Hello ```` ````{tab-item} Embedding -1. You will first need to upload your media to the repository. Navigate to the folder called figures(`book/figures`) and make sure you are i the right branch. On the right top, click on `Add file` and `Upload new file`. +1. You will first need to upload your media to the repository. Navigate to the folder called figures(`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file > Upload new file`. 2. Choose the visual media you want to upload. Remember its file name as you will need it later. @@ -18,9 +18,9 @@ Hello 4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. -5. Copy this syntax +5. Copy this syntax and adjust the file name, width, alignment and caption. -```python +```md ```{figure} figures/<new_figure>.PNG --- @@ -28,13 +28,12 @@ width: 80% align: center name: my_new_figure --- -New figure - +<caption> ``` + ``` ```{Warning} - Make sure the file extension of your figure is correct because markdown differentiates capital letters! ``` From 83d5cf4b0664f6c1fe2515c6967a280c071353ec Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 24 Feb 2025 18:11:28 +0100 Subject: [PATCH 21/54] again update --- book/_toc.yml | 1 + book/exercises/007.md | 6 +++--- book/exercises/010.md | 3 +++ book/exercises/type4.md | 1 - 4 files changed, 7 insertions(+), 4 deletions(-) create mode 100644 book/exercises/010.md diff --git a/book/_toc.yml b/book/_toc.yml index f5ebf5d..9073c86 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -25,6 +25,7 @@ parts: - file: exercises/type4.mb sections: - file: exercises/009.md + - file: exercises/010.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/007.md b/book/exercises/007.md index 745a2a0..e16dbf7 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -16,9 +16,9 @@ More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyt # Chapter Title ## Section Title ### Subsection Title -#### Smaller Heading -##### Heading level 5 -###### Heading level 6 +#### Heading +##### Smaller Heading +###### Smallest Heading ``` 3. Add some text to the (sub)sections to complete your chapter. diff --git a/book/exercises/010.md b/book/exercises/010.md new file mode 100644 index 0000000..8c8990e --- /dev/null +++ b/book/exercises/010.md @@ -0,0 +1,3 @@ +# Exercise 10: ... + +ghkvkhg \ No newline at end of file diff --git a/book/exercises/type4.md b/book/exercises/type4.md index 59eaaa7..df8b1b4 100644 --- a/book/exercises/type4.md +++ b/book/exercises/type4.md @@ -1,4 +1,3 @@ # User type 4 - User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). Using this skills, this user type can take the role as editor, managing more than just book content. \ No newline at end of file From 3fdb786d320339fcecd578837323d32c8afe4ecc Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Wed, 26 Feb 2025 17:10:03 +0100 Subject: [PATCH 22/54] Update credits.md --- book/credits.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/credits.md b/book/credits.md index 89b23d8..40a0a5e 100644 --- a/book/credits.md +++ b/book/credits.md @@ -3,11 +3,11 @@ You can refer to this book as: -> `<editors>` (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo` +> `<editors>` (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`. CC BY 4.0. You can refer to individual chapters or pages within this book as: -> `<Title of Chapter or Page>`. In `<editors>` (`<year>`) _`<title>`_. `<url to specific page on book website>`. Source files at `<link to specific commit / file in github repo` +> `<Title of Chapter or Page>`. In `<editors>` (`<year>`) _`<title>`_. `<url to specific page on book website>`. Source files at `<link to specific commit / file in github repo`. CC BY 4.0. We anticipate that the content of this book will change significantly. Therefore, we recommend using the source code directly with the citation above that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. However, we make no guarantee, so if it is important for you to reference a specific location/commit within the book. From 7b51db6960f9672fda6b03ca536be58dd5280b0f Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Sat, 1 Mar 2025 22:47:26 +0100 Subject: [PATCH 23/54] embedding --- book/exercises/008.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index ce31697..2c0ff50 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -5,12 +5,24 @@ To help you illustrate your content, it can be sueful to add some type of visual `````{tab-set} ````{tab-item} Linking -Hello +Embed a video + +```{embed} https://www.youtube.com/watch?v=gbBsWo6em4c +:width: 700 +:height: 400 +``` +also video + +```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg +:width: 700 +:height: 400 +``` + ```` ````{tab-item} Embedding -1. You will first need to upload your media to the repository. Navigate to the folder called figures(`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file > Upload new file`. +1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file > Upload new file`. 2. Choose the visual media you want to upload. Remember its file name as you will need it later. From 313d811ad1c45213f475ea1d410c80f2712844e9 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 21:58:39 +0100 Subject: [PATCH 24/54] fixing embed --- book/exercises/008.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index 2c0ff50..ccd56ee 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -5,19 +5,39 @@ To help you illustrate your content, it can be sueful to add some type of visual `````{tab-set} ````{tab-item} Linking -Embed a video +In Jupyter Book, you can embed a YouTube video using the `{iframe}` directive, ensuring you use the embed URL format. +```md -```{embed} https://www.youtube.com/watch?v=gbBsWo6em4c +```{iframe} https://www.youtube.com/embed/watch?v=gbBsWo6em4c :width: 700 :height: 400 ``` -also video +``` +For example, the above code cell, will result in the following video. + +```{iframe} https://www.youtube.com/embed/watch?v=gbBsWo6em4c +:width: 700 +:height: 400 +``` + +To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. + +```md ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg :width: 700 :height: 400 + +My new figure ``` - +``` + +```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg +:width: 700 +:height: 400 + +My new figure +``` ```` ````{tab-item} Embedding From 8a0b9e0a1bc94330590a52409f8dcc2c2a47cd60 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 22:12:17 +0100 Subject: [PATCH 25/54] fix embed 2 --- book/exercises/008.md | 43 +++++++++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index ccd56ee..4083ddc 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -6,18 +6,28 @@ To help you illustrate your content, it can be sueful to add some type of visual ````{tab-item} Linking In Jupyter Book, you can embed a YouTube video using the `{iframe}` directive, ensuring you use the embed URL format. + ```md -```{iframe} https://www.youtube.com/embed/watch?v=gbBsWo6em4c -:width: 700 -:height: 400 +```{iframe} https://www.youtube.com/embed/x2eonqw5M6o +--- +width: 80% +align: center +name: my_linked_video +--- +<caption> ``` + ``` For example, the above code cell, will result in the following video. -```{iframe} https://www.youtube.com/embed/watch?v=gbBsWo6em4c -:width: 700 -:height: 400 +```{iframe} https://www.youtube.com/embed/x2eonqw5M6o +--- +width: 80% +align: center +name: my_linked_video +--- +<caption> ``` To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. @@ -25,18 +35,23 @@ To link and display an online figure, you can use the `{figure}` directive, whic ```md ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg -:width: 700 -:height: 400 - -My new figure +--- +width: 80% +align: center +name: my_linked_figure +--- +<caption> ``` + ``` ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg -:width: 700 -:height: 400 - -My new figure +--- +width: 80% +align: center +name: my_linked_figure +--- +<caption> ``` ```` From 6f407ddebe0a7d982d9ef372b147c6430d849c00 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 22:20:08 +0100 Subject: [PATCH 26/54] Update 008.md --- book/exercises/008.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index 4083ddc..6d55509 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -7,8 +7,7 @@ To help you illustrate your content, it can be sueful to add some type of visual In Jupyter Book, you can embed a YouTube video using the `{iframe}` directive, ensuring you use the embed URL format. -```md - +<!-- ```md ```{iframe} https://www.youtube.com/embed/x2eonqw5M6o --- width: 80% @@ -17,7 +16,6 @@ name: my_linked_video --- <caption> ``` - ``` For example, the above code cell, will result in the following video. @@ -28,12 +26,11 @@ align: center name: my_linked_video --- <caption> -``` +``` --> To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. ```md - ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg --- width: 80% @@ -42,7 +39,6 @@ name: my_linked_figure --- <caption> ``` - ``` ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg @@ -68,7 +64,6 @@ name: my_linked_figure 5. Copy this syntax and adjust the file name, width, alignment and caption. ```md - ```{figure} figures/<new_figure>.PNG --- width: 80% @@ -77,7 +72,6 @@ name: my_new_figure --- <caption> ``` - ``` ```{Warning} From 0a9b850a64d007f1587fbc7f1ac88c4619774339 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 22:34:14 +0100 Subject: [PATCH 27/54] Update 008.md --- book/exercises/008.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index 6d55509..b1cad3e 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -16,7 +16,8 @@ name: my_linked_video --- <caption> ``` -``` +``` --> + For example, the above code cell, will result in the following video. ```{iframe} https://www.youtube.com/embed/x2eonqw5M6o @@ -26,11 +27,11 @@ align: center name: my_linked_video --- <caption> -``` --> +``` To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. -```md +<!-- ```md ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg --- width: 80% @@ -39,7 +40,7 @@ name: my_linked_figure --- <caption> ``` -``` +``` --> ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg --- @@ -63,7 +64,7 @@ name: my_linked_figure 5. Copy this syntax and adjust the file name, width, alignment and caption. -```md +<!-- ```md ```{figure} figures/<new_figure>.PNG --- width: 80% @@ -72,6 +73,15 @@ name: my_new_figure --- <caption> ``` +``` --> + +```{figure} figures/<new_figure>.PNG +--- +width: 80% +align: center +name: my_new_figure +--- +<caption> ``` ```{Warning} From 9b69d8bfc8b26e9da85d25336f659cb708b550ee Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 22:38:29 +0100 Subject: [PATCH 28/54] Update 008.md --- book/exercises/008.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index b1cad3e..de90b16 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -21,12 +21,9 @@ name: my_linked_video For example, the above code cell, will result in the following video. ```{iframe} https://www.youtube.com/embed/x2eonqw5M6o ---- -width: 80% -align: center -name: my_linked_video ---- -<caption> +:width: 80% +:align: center +:name: my_new_video ``` To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. From 1cb5bde1b0173a3d0e7bca47b3b6f733b2e58d0d Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 22:49:35 +0100 Subject: [PATCH 29/54] final --- book/exercises/008.md | 89 ++++++++++++------------------------------- 1 file changed, 24 insertions(+), 65 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index de90b16..7ce8c12 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -1,54 +1,8 @@ # Exercise 8: Add visual media -To help you illustrate your content, it can be sueful to add some type of visual media such as figures, videos or gifs. If you want to add a figure/gif/video to you book, you can refer to another website. This is quite handy for video's but it does carry the risk that this figure/gif/video will no longer be visible if the location is changed. So it is better to add the source directly to the book. +To help you illustrate your content, it can be sueful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to another website. This is quite handy but it does carry the risk that this figure/gif will no longer be visible if the location is changed. So it is better to add the source directly to the book. `````{tab-set} -````{tab-item} Linking - -In Jupyter Book, you can embed a YouTube video using the `{iframe}` directive, ensuring you use the embed URL format. - -<!-- ```md -```{iframe} https://www.youtube.com/embed/x2eonqw5M6o ---- -width: 80% -align: center -name: my_linked_video ---- -<caption> -``` -``` --> - -For example, the above code cell, will result in the following video. - -```{iframe} https://www.youtube.com/embed/x2eonqw5M6o -:width: 80% -:align: center -:name: my_new_video -``` - -To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. - -<!-- ```md -```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg ---- -width: 80% -align: center -name: my_linked_figure ---- -<caption> -``` -``` --> - -```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg ---- -width: 80% -align: center -name: my_linked_figure ---- -<caption> -``` - -```` ````{tab-item} Embedding 1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file > Upload new file`. @@ -61,25 +15,15 @@ name: my_linked_figure 5. Copy this syntax and adjust the file name, width, alignment and caption. -<!-- ```md -```{figure} figures/<new_figure>.PNG ---- -width: 80% -align: center -name: my_new_figure ---- -<caption> -``` -``` --> -```{figure} figures/<new_figure>.PNG ---- -width: 80% -align: center -name: my_new_figure ---- -<caption> -``` + ```{figure} figures/<new_figure>.PNG + --- + width: 80% + align: center + name: my_new_figure + --- + <caption> + ``` ```{Warning} Make sure the file extension of your figure is correct because markdown differentiates capital letters! @@ -93,6 +37,21 @@ Make sure the file extension of your figure is correct because markdown differen 9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +```` +````{tab-item} Linking + +To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. + + + ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg + --- + width: 80% + align: center + name: my_linked_figure + --- + <caption> + ``` + ```` ````` From 437bedb1424e879bedf49cc95be5271c76b87c0a Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 23:04:59 +0100 Subject: [PATCH 30/54] user type 4 --- book/_toc.yml | 2 +- book/exercises/008.md | 3 --- book/exercises/009.md | 24 ++++++++++++++---------- book/exercises/010.md | 5 ++++- book/exercises/type3.md | 5 ++--- book/exercises/type4.md | 6 +++++- 6 files changed, 26 insertions(+), 19 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 9073c86..29d5ac6 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -22,7 +22,7 @@ parts: sections: - file: exercises/007.md - file: exercises/008.md - - file: exercises/type4.mb + - file: exercises/type4.md sections: - file: exercises/009.md - file: exercises/010.md diff --git a/book/exercises/008.md b/book/exercises/008.md index 7ce8c12..3068f1f 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -15,7 +15,6 @@ To help you illustrate your content, it can be sueful to add some type of visual 5. Copy this syntax and adjust the file name, width, alignment and caption. - ```{figure} figures/<new_figure>.PNG --- width: 80% @@ -42,7 +41,6 @@ Make sure the file extension of your figure is correct because markdown differen To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. - ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg --- width: 80% @@ -51,7 +49,6 @@ To link and display an online figure, you can use the `{figure}` directive, whic --- <caption> ``` - ```` ````` diff --git a/book/exercises/009.md b/book/exercises/009.md index a49a9c9..9f389b4 100644 --- a/book/exercises/009.md +++ b/book/exercises/009.md @@ -1,10 +1,14 @@ # Exercise 9: Referencing using target headers -It can be really useful to refer to a specific section in your book while working in a different file. Referencing can be done using target headers. (<title>)= +It can be really useful to refer to a specific section in your book while working in a different file. Referencing can be done using target headers such as: + +``` +(<title>)= +``` 1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. -2. Identify the section you want to reference and name it ebtween bracketsfor example exercise_1. +2. Identify the section you want to reference and name it between brackets for example `exercise_`1. ``` (exercise_1)= @@ -14,21 +18,21 @@ Let's start with the most basic edit: add some text to a file and see that the w ``` -3. Referncing +3. Referencing -There are three types of referencing +There are three types of referencing: -If you want to refernce in line you can use: +* If you want to refernce in line you can use: -My favourte exercise was {ref}`exercise_1`. +My favourite exercise was {ref}`exercise_1`. ``` My favourte exercise was {ref}`exercise_1`. ``` -You can specify the text of the target: +* You can also specify the in-line text of the target (aka what the link will say): -{ref}`MyST syntax lecture <exercise_1>` +{ref}`Best exercise <exercise_1>` -Another alternative is to use Markdown syntax: +* Another alternative is to use Markdown syntax: -[MyST syntax lecture](exercise_1) \ No newline at end of file +[Best exercose](exercise_1) \ No newline at end of file diff --git a/book/exercises/010.md b/book/exercises/010.md index 8c8990e..05bbfde 100644 --- a/book/exercises/010.md +++ b/book/exercises/010.md @@ -1,3 +1,6 @@ # Exercise 10: ... -ghkvkhg \ No newline at end of file +```{attention} + +Under Construction +``` \ No newline at end of file diff --git a/book/exercises/type3.md b/book/exercises/type3.md index 7c67e14..c221588 100644 --- a/book/exercises/type3.md +++ b/book/exercises/type3.md @@ -4,6 +4,5 @@ Now that you've made your own version of the book, it's time to add some content Exercises for user type 3 relate to: -- File Structure (Markdown) -- In-text referencing -- Adding a figure \ No newline at end of file +- [File structure (Markdown)](007.md) +- [Adding visual media](008.md) \ No newline at end of file diff --git a/book/exercises/type4.md b/book/exercises/type4.md index df8b1b4..9986582 100644 --- a/book/exercises/type4.md +++ b/book/exercises/type4.md @@ -1,3 +1,7 @@ # User type 4 -User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required). Using this skills, this user type can take the role as editor, managing more than just book content. \ No newline at end of file +User 4 is a hybrid between type 3 and 5. As user type 4 you will mainly be making changes by editing the `.md` files locally using, for example, VS Code. + +Exercises for user type 4 relate to: + +- [Referencing](009.md) From d4a2b8d60e20d617eb145939c8edb5d2fa1f6377 Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 23:14:03 +0100 Subject: [PATCH 31/54] referencing --- book/exercises/008.md | 18 ++++++++++-------- book/exercises/009.md | 25 ++++++++++++++++--------- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index 3068f1f..152ff39 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -15,14 +15,16 @@ To help you illustrate your content, it can be sueful to add some type of visual 5. Copy this syntax and adjust the file name, width, alignment and caption. - ```{figure} figures/<new_figure>.PNG - --- - width: 80% - align: center - name: my_new_figure - --- - <caption> - ``` +```md +```{figure} figures/<new_figure>.PNG +--- +width: 80% +align: center +name: my_new_figure +--- +<caption> +``` +``` ```{Warning} Make sure the file extension of your figure is correct because markdown differentiates capital letters! diff --git a/book/exercises/009.md b/book/exercises/009.md index 9f389b4..9747022 100644 --- a/book/exercises/009.md +++ b/book/exercises/009.md @@ -8,7 +8,7 @@ It can be really useful to refer to a specific section in your book while worki 1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. -2. Identify the section you want to reference and name it between brackets for example `exercise_`1. +2. Identify the section you want to reference and name it between brackets for example `exercise_1`. ``` (exercise_1)= @@ -18,21 +18,28 @@ Let's start with the most basic edit: add some text to a file and see that the w ``` -3. Referencing +3. There are three types of referencing: -There are three types of referencing: - -* If you want to refernce in line you can use: +* You can use the standard title text which will be the title after the target header My favourite exercise was {ref}`exercise_1`. ``` My favourte exercise was {ref}`exercise_1`. ``` -* You can also specify the in-line text of the target (aka what the link will say): +* You can also specify the title text of the target header (aka specify what the link will say): -{ref}`Best exercise <exercise_1>` +My favourite exercise was {ref}`the first one <exercise_1>`. -* Another alternative is to use Markdown syntax: +``` +My favourite exercise was {ref}`the first one <exercise_1>`. +``` + +* You can also use Markdown syntax, then the title text is also fully customizable. + +My favourite exercise was [this one](exercise_1). + +``` +My favourite exercise was [this one](exercise_1). +``` -[Best exercose](exercise_1) \ No newline at end of file From 9b5204f1689a4e3291f085d1f2664616a4e6115b Mon Sep 17 00:00:00 2001 From: Julie Kirsch <julie.kirsch@pt.lu> Date: Mon, 3 Mar 2025 23:18:38 +0100 Subject: [PATCH 32/54] typo --- book/exercises/008.md | 20 ++++++++++---------- book/exercises/009.md | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index 152ff39..b122b81 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -15,16 +15,16 @@ To help you illustrate your content, it can be sueful to add some type of visual 5. Copy this syntax and adjust the file name, width, alignment and caption. -```md -```{figure} figures/<new_figure>.PNG ---- -width: 80% -align: center -name: my_new_figure ---- -<caption> -``` -``` + + ```{figure} figures/<new_figure>.PNG + --- + width: 80% + align: center + name: my_new_figure + --- + <caption> + ``` + ```{Warning} Make sure the file extension of your figure is correct because markdown differentiates capital letters! diff --git a/book/exercises/009.md b/book/exercises/009.md index 9747022..34a5d45 100644 --- a/book/exercises/009.md +++ b/book/exercises/009.md @@ -25,7 +25,7 @@ Let's start with the most basic edit: add some text to a file and see that the w My favourite exercise was {ref}`exercise_1`. ``` -My favourte exercise was {ref}`exercise_1`. +My favourite exercise was {ref}`exercise_1`. ``` * You can also specify the title text of the target header (aka specify what the link will say): From 97a8274eb03d12ad54fb126d37d9386851311234 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame <r.c.lanzafame@tudelft.nl> Date: Tue, 4 Mar 2025 06:28:07 +0100 Subject: [PATCH 33/54] add note about visual file types --- book/exercises/008.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/book/exercises/008.md b/book/exercises/008.md index b122b81..8e7c72d 100644 --- a/book/exercises/008.md +++ b/book/exercises/008.md @@ -1,6 +1,10 @@ # Exercise 8: Add visual media -To help you illustrate your content, it can be sueful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to another website. This is quite handy but it does carry the risk that this figure/gif will no longer be visible if the location is changed. So it is better to add the source directly to the book. +To help you illustrate your content, it can be sueful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). + +```{note} +Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows (especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned! +``` `````{tab-set} ````{tab-item} Embedding From 0bdb1d31a1b61ab66f7f0b74fdd63e411e858f39 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 07:50:01 +0100 Subject: [PATCH 34/54] Edits TOm --- book/_toc.yml | 13 ++-- book/{exercises => }/exercises.md | 2 +- book/exercises/007.md | 32 ---------- book/exercises/010.md | 6 -- book/exercises/advanced_exercises.md | 5 -- book/exercises/type3.md | 8 --- book/exercises/type4.md | 7 --- book/syntax_exercises.md | 5 ++ book/syntax_exercises/007.md | 66 +++++++++++++++++++++ book/{exercises => syntax_exercises}/008.md | 64 ++++++++++---------- book/{exercises => syntax_exercises}/009.md | 0 11 files changed, 109 insertions(+), 99 deletions(-) rename book/{exercises => }/exercises.md (97%) delete mode 100644 book/exercises/007.md delete mode 100644 book/exercises/010.md delete mode 100644 book/exercises/advanced_exercises.md delete mode 100644 book/exercises/type3.md delete mode 100644 book/exercises/type4.md create mode 100644 book/syntax_exercises.md create mode 100644 book/syntax_exercises/007.md rename book/{exercises => syntax_exercises}/008.md (57%) rename book/{exercises => syntax_exercises}/009.md (100%) diff --git a/book/_toc.yml b/book/_toc.yml index 29d5ac6..954403c 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -16,16 +16,11 @@ parts: - file: exercises/005.md - file: exercises/006.md - file: exercises/summary - - file: exercises/advanced_exercises.md + - file: exercises/syntax_exercises.md sections: - - file: exercises/type3.md - sections: - - file: exercises/007.md - - file: exercises/008.md - - file: exercises/type4.md - sections: - - file: exercises/009.md - - file: exercises/010.md + - file: syntax_exercises/007.md + - file: syntax_exercises/008.md + - file: syntax_exercises/009.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/exercises.md b/book/exercises.md similarity index 97% rename from book/exercises/exercises.md rename to book/exercises.md index e885fe5..491c7a4 100644 --- a/book/exercises/exercises.md +++ b/book/exercises.md @@ -1,4 +1,4 @@ -# Exercises +# Exercises TeachBooks workflow Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. We welcome you to work through the exercises attached to this page (you can find them in the left sidebar). diff --git a/book/exercises/007.md b/book/exercises/007.md deleted file mode 100644 index e16dbf7..0000000 --- a/book/exercises/007.md +++ /dev/null @@ -1,32 +0,0 @@ -# Exercise 7: File Structure (Markdown) - -In this exercise you will learn how to structure your chapters. - -```{tip} - -More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). - -``` - -1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. - -2. Let's create the structure of your chapter. You can start by adding a title to the section. The title is always defined in the first line of the file after the hashtag `#`. Then you can also add sections and subsections as needed. - -``` -# Chapter Title -## Section Title -### Subsection Title -#### Heading -##### Smaller Heading -###### Smallest Heading -``` - -3. Add some text to the (sub)sections to complete your chapter. - -4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. - -5. Add a commit message. - -6. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting (user type 4)) - -7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. diff --git a/book/exercises/010.md b/book/exercises/010.md deleted file mode 100644 index 05bbfde..0000000 --- a/book/exercises/010.md +++ /dev/null @@ -1,6 +0,0 @@ -# Exercise 10: ... - -```{attention} - -Under Construction -``` \ No newline at end of file diff --git a/book/exercises/advanced_exercises.md b/book/exercises/advanced_exercises.md deleted file mode 100644 index e56629f..0000000 --- a/book/exercises/advanced_exercises.md +++ /dev/null @@ -1,5 +0,0 @@ -# Advanced exercises - -The previous exercise guide you through making your own book. Now lets get specific! - -This chapter includes a couple of more exercises directed to the different user types. \ No newline at end of file diff --git a/book/exercises/type3.md b/book/exercises/type3.md deleted file mode 100644 index c221588..0000000 --- a/book/exercises/type3.md +++ /dev/null @@ -1,8 +0,0 @@ -# User Type 3 - -Now that you've made your own version of the book, it's time to add some content. As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while ipynb` files contain both text and executable code cells. In this exercise you will learn how to structure a `.md` file. - -Exercises for user type 3 relate to: - -- [File structure (Markdown)](007.md) -- [Adding visual media](008.md) \ No newline at end of file diff --git a/book/exercises/type4.md b/book/exercises/type4.md deleted file mode 100644 index 9986582..0000000 --- a/book/exercises/type4.md +++ /dev/null @@ -1,7 +0,0 @@ -# User type 4 - -User 4 is a hybrid between type 3 and 5. As user type 4 you will mainly be making changes by editing the `.md` files locally using, for example, VS Code. - -Exercises for user type 4 relate to: - -- [Referencing](009.md) diff --git a/book/syntax_exercises.md b/book/syntax_exercises.md new file mode 100644 index 0000000..5c7c975 --- /dev/null +++ b/book/syntax_exercises.md @@ -0,0 +1,5 @@ +# Syntax exercises + +The previous exercise guide you through making your own book following the TeachBooks workflow. Now lets get specific and dive into the possibilities of the syntax used! + +As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! \ No newline at end of file diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md new file mode 100644 index 0000000..6fe0ddb --- /dev/null +++ b/book/syntax_exercises/007.md @@ -0,0 +1,66 @@ +# Exercise 7: File Structure (Markdown) + +In this exercise you will learn how to structure your chapters. + +::::::{topic} Exercise objective +Can you structure your page with a title and (sub)sections? +:::::: + +```{tip} + +More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). + +``` + +1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch.. When you've arrived there, click `Add file` - {octicon}`plus;1em`. + +2. Name your file and end it with the file extension `.md` (e.g. `my_new_file.md`), your filename preferable shouldn't include spaces. + +3. Now let's create the structure of your chapter. You need to start with a title on the top of this page. The title is always defined in one of the first lines of the file after the hashtag `#`. So your file should look like: + +```md +# Chapter title + +``` + +4. Now let's add some more text and subsections as needed. You're only allowed to use one chapter title `#`, but there's no limit for the amount of sections, subsections, etc: + +```md +# Chapter Title +text + +## Section Title 1 +text + +## Section Title 2 +text + +### Subsection Title 1 +text + +### Subsection Title 2 +text + +#### Heading +##### Smaller Heading +###### Smallest Heading +``` + +5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +6. Add a commit message. + +7. Now let's add your new file tot the table of contents, as explained in [](../exercises/002.md). + +8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? Soon, 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: +- What is the correct way to define a title in a Markdown file? +- How many chapter titles (`#`) are allowed in a single Markdown file? +- What file type are you using? +``` \ No newline at end of file diff --git a/book/exercises/008.md b/book/syntax_exercises/008.md similarity index 57% rename from book/exercises/008.md rename to book/syntax_exercises/008.md index 8e7c72d..76806c8 100644 --- a/book/exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,60 +1,62 @@ # Exercise 8: Add visual media -To help you illustrate your content, it can be sueful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). +To help you illustrate your content, it can be useful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). + +::::::{topic} Exercise objective +Can you add figures to your page? +:::::: ```{note} -Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows (especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned! +Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows, especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned!). ``` -`````{tab-set} -````{tab-item} Embedding -1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file > Upload new file`. +1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file` - {octicon}`upload;1em` `Upload new file`. Note that you can store your files in another folder within the book directory too. However it's good practice to store figures in a separate folder (eventually per chapter). -2. Choose the visual media you want to upload. Remember its file name as you will need it later. +2. Choose the visual media you want to upload. Remember its file name, including its file extension as you will need it later. 3. Commit your changes. -4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. +4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the same branch as where you've added your figure. -5. Copy this syntax and adjust the file name, width, alignment and caption. +5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#block-level-images)): +````md +```{figure} figures/<new_figure>.png +:width: 80% +:align: center - ```{figure} figures/<new_figure>.PNG - --- - width: 80% - align: center - name: my_new_figure - --- - <caption> - ``` - +<caption text> +``` +```` ```{Warning} Make sure the file extension of your figure is correct because markdown differentiates capital letters! ``` +```{Warning} +If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folder above the current page>` ) +``` + +6. To link and display an online figure, you can use the same `{figure}` directive. Just past in the : + +````md +```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg +:width: 80% +:align: center + +<caption> +``` +```` + 6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. 7. Add a commit message. -8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting (user type 4)) +8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (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. -```` -````{tab-item} Linking -To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references. - ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg - --- - width: 80% - align: center - name: my_linked_figure - --- - <caption> - ``` -```` -````` diff --git a/book/exercises/009.md b/book/syntax_exercises/009.md similarity index 100% rename from book/exercises/009.md rename to book/syntax_exercises/009.md From 4913d2c5929478c92a1dbf1be544569916491327 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 07:52:04 +0100 Subject: [PATCH 35/54] fix --- book/_toc.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 954403c..91a0b9f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -7,7 +7,7 @@ parts: - file: some_content/overview.md sections: - file: some_content/text_and_code.ipynb - - file: exercises/exercises.md + - file: exercises.md sections: - file: exercises/001.md - file: exercises/002.md @@ -16,7 +16,7 @@ parts: - file: exercises/005.md - file: exercises/006.md - file: exercises/summary - - file: exercises/syntax_exercises.md + - file: syntax_exercises.md sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md From bb3608abeddb5c3fd3056fcb0ba8f81afbb42ce0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 07:59:54 +0100 Subject: [PATCH 36/54] fixes --- book/syntax_exercises.md | 4 +++- book/syntax_exercises/007.md | 2 +- book/syntax_exercises/008.md | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/book/syntax_exercises.md b/book/syntax_exercises.md index 5c7c975..b8b49ef 100644 --- a/book/syntax_exercises.md +++ b/book/syntax_exercises.md @@ -2,4 +2,6 @@ The previous exercise guide you through making your own book following the TeachBooks workflow. Now lets get specific and dive into the possibilities of the syntax used! -As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! \ No newline at end of file +As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! + +The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) which will come in handy! \ No newline at end of file diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md index 6fe0ddb..cd931c0 100644 --- a/book/syntax_exercises/007.md +++ b/book/syntax_exercises/007.md @@ -12,7 +12,7 @@ More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyt ``` -1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch.. When you've arrived there, click `Add file` - {octicon}`plus;1em`. +1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch.. When you've arrived there, click `Add file` - {octicon}`plus;1em` `Create new file`. 2. Name your file and end it with the file extension `.md` (e.g. `my_new_file.md`), your filename preferable shouldn't include spaces. diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 76806c8..0451b84 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -53,7 +53,7 @@ If your figure is in a different directory than your chapter, you'll need to ref 7. Add a commit message. -8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting) +8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (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. From cf749236c62a54eb0c6772dac1263e3436c501e8 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:00:05 +0100 Subject: [PATCH 37/54] test syntax --- 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 eb7ce52..40f6e51 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -19,9 +19,8 @@ Can you add some content to the intro page? :class: dropdown ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true ---- -name: template_demo_public ---- +:name: template_demo_public + Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco) ``` From 7e9aeacb11efd694895f60df1a00ef7ce0109fc7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:10:03 +0100 Subject: [PATCH 38/54] WIP --- book/syntax_exercises/008.md | 9 ++++++++- book/syntax_exercises/009.md | 8 ++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 0451b84..7c14b2f 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -57,6 +57,13 @@ If your figure is in a different directory than your chapter, you'll need to ref 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: +- Where should you upload your visual media files in the repository? +- What is the recommended practice for storing figures in the book directory? +- What should you be cautious about when specifying the file extension of your figure? +- How do you refer to a figure located in a different directory than your chapter? - +``` \ No newline at end of file diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 34a5d45..c228e49 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,10 +1,10 @@ # Exercise 9: Referencing using target headers -It can be really useful to refer to a specific section in your book while working in a different file. Referencing can be done using target headers such as: +It can be really useful to refer to a specific section in your book while working in a different file. -``` -(<title>)= -``` +::::::{topic} Exercise objective +Can you add cross-references to headers? +:::::: 1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. From a6478d523a4403fb2f6b32f615d0a8ff72cc6a45 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:10:43 +0100 Subject: [PATCH 39/54] remove exercise 9 for now --- book/_toc.yml | 1 - book/syntax_exercises/009.md | 45 ------------------------------------ 2 files changed, 46 deletions(-) delete mode 100644 book/syntax_exercises/009.md diff --git a/book/_toc.yml b/book/_toc.yml index 91a0b9f..ad5003f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -20,7 +20,6 @@ parts: sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md - - file: syntax_exercises/009.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md deleted file mode 100644 index c228e49..0000000 --- a/book/syntax_exercises/009.md +++ /dev/null @@ -1,45 +0,0 @@ -# Exercise 9: Referencing using target headers - -It can be really useful to refer to a specific section in your book while working in a different file. - -::::::{topic} Exercise objective -Can you add cross-references to headers? -:::::: - -1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch. - -2. Identify the section you want to reference and name it between brackets for example `exercise_1`. - -``` -(exercise_1)= -# 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... - -``` - -3. There are three types of referencing: - -* You can use the standard title text which will be the title after the target header - -My favourite exercise was {ref}`exercise_1`. - -``` -My favourite exercise was {ref}`exercise_1`. -``` -* You can also specify the title text of the target header (aka specify what the link will say): - -My favourite exercise was {ref}`the first one <exercise_1>`. - -``` -My favourite exercise was {ref}`the first one <exercise_1>`. -``` - -* You can also use Markdown syntax, then the title text is also fully customizable. - -My favourite exercise was [this one](exercise_1). - -``` -My favourite exercise was [this one](exercise_1). -``` - From d92980f80d9e99bd20a798a18d028b870a26e615 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:12:34 +0100 Subject: [PATCH 40/54] fix? --- book/exercises/001.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index 40f6e51..a80ef53 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -17,10 +17,8 @@ Can you add some content to the intro page? ````{hint} Watch the steps in action below :class: dropdown - ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true :name: template_demo_public - Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco) ``` From 1e3202b0cb0c9a61ea336b3d5e51e622d4c7b167 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:14:01 +0100 Subject: [PATCH 41/54] Update 008.md --- book/syntax_exercises/008.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 7c14b2f..ab7caf1 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -25,7 +25,6 @@ Unless you are using a file format like `*.svg`, the raw contents of a visual me ```{figure} figures/<new_figure>.png :width: 80% :align: center - <caption text> ``` ```` @@ -44,7 +43,6 @@ If your figure is in a different directory than your chapter, you'll need to ref ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg :width: 80% :align: center - <caption> ``` ```` From 43acecdaca197ff7bc98c94e63956971b6d8a94d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:16:11 +0100 Subject: [PATCH 42/54] fix? --- book/exercises/001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index a80ef53..f1b3af3 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -17,12 +17,12 @@ Can you add some content to the intro page? ````{hint} Watch the steps in action below :class: dropdown + ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true :name: template_demo_public + Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco) ``` - - ```` ::::{card} Check your understanding From 31966fde1a2acfa6c8d68b9549607fca977da8c4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:17:31 +0100 Subject: [PATCH 43/54] back to previous syntax --- book/exercises/001.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index f1b3af3..6ab67b9 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -19,8 +19,9 @@ Can you add some content to the intro page? :class: dropdown ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true -:name: template_demo_public - +--- +name: template_demo_public +--- Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco) ``` ```` From f6897186ba428de286a0add7994c40c474426efc Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:18:34 +0100 Subject: [PATCH 44/54] revert old syntax --- book/syntax_exercises/008.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index ab7caf1..336bbd8 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -19,12 +19,14 @@ Unless you are using a file format like `*.svg`, the raw contents of a visual me 4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the same branch as where you've added your figure. -5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#block-level-images)): +5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/figures.html#figure-parameters)): ````md ```{figure} figures/<new_figure>.png -:width: 80% -:align: center +--- +width: 80% +align: center +--- <caption text> ``` ```` @@ -41,8 +43,10 @@ If your figure is in a different directory than your chapter, you'll need to ref ````md ```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg -:width: 80% -:align: center +--- +width: 80% +align: center +--- <caption> ``` ```` From efc9c7af09e0aa576fb0f437f9c813c35800ad16 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 08:21:48 +0100 Subject: [PATCH 45/54] fix? --- book/exercises/001.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index 6ab67b9..bf4adaf 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -16,8 +16,9 @@ Can you add some content to the intro page? 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!). ````{hint} Watch the steps in action below -:class: dropdown - +--- +class: dropdown +--- ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true --- name: template_demo_public From 1b03f1f6eaace9bb917759135e0ea24561b7a0d0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 10:32:44 +0100 Subject: [PATCH 46/54] tyop --- book/syntax_exercises/008.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 336bbd8..59c792b 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -36,7 +36,7 @@ Make sure the file extension of your figure is correct because markdown differen ``` ```{Warning} -If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folder above the current page>` ) +If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folders above the current page>` ) ``` 6. To link and display an online figure, you can use the same `{figure}` directive. Just past in the : From 5b82884a5b3e7167288f5008c3669f50b82a5e47 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 10:33:04 +0100 Subject: [PATCH 47/54] fix? --- book/exercises/001.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index bf4adaf..c230a3c 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -16,9 +16,8 @@ Can you add some content to the intro page? 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!). ````{hint} Watch the steps in action below ---- class: dropdown ---- + ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true --- name: template_demo_public From e495a7caa61a9b68cc78137d180d3304f213577e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 10:34:40 +0100 Subject: [PATCH 48/54] fix errors --- book/changelog.md | 2 +- book/credits.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/book/changelog.md b/book/changelog.md index 23465d6..b9de8fa 100644 --- a/book/changelog.md +++ b/book/changelog.md @@ -3,7 +3,7 @@ ## `<latest version>`: `<date>` - `<Added/modified/deleted>` [](`<relative link to changed file>`) - ... -- Full Changelog: `[<previous version>...<current version>](<link to diff as provided by GitHub>)' +- Full Changelog: `[<previous version>...<current version>](<link to diff as provided by GitHub>)` ## `<previous version>`: <...> - <...> diff --git a/book/credits.md b/book/credits.md index 40a0a5e..c8de8bb 100644 --- a/book/credits.md +++ b/book/credits.md @@ -24,10 +24,10 @@ This manual is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/ Parts of this book are taken from other external resources and reused in various ways. If an author is not listed on a particular page, it is by the Authors, except as follows: The following pages are included directly from an external resource and is not edited by `<Editor>`: -- page [](). Original content licensed under CC BY 4.0 License +- page `[](<relative_link_to_page>)`. Original content licensed under CC BY 4.0 License The following pages contain content written by others, part of has been reused and/or modified by `<Editor>` -- Page []() include text from {cite:t}`jason_moore`. Original content licensed under CC BY. +- Page `[](<relative_link_to_page>)` include text from {cite:t}`jason_moore`. Original content licensed under CC BY. (editor)= From 61592c0d09d5b0f2caca4677db33680d2d93bc6b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 10:38:21 +0100 Subject: [PATCH 49/54] Update README.md --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 6b38bd6..3c9eef7 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Your first TeachBook using the GitHub template -[![call-deploy-book](https://github.com/TeachBooks/template/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TeachBooks/template/actions/workflows/call-deploy-book.yml) - The template allows you to start your own TeachBook and hosting that TeachBook online without knowledge on Git, the Jupyter book package, python or anaconda. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book. Please look at our manual (https://teachbooks.io/manual) to find more about that! ## How to get started From 903e7e92db9b1d78b771e3ca738074cbac620433 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 10:51:08 +0100 Subject: [PATCH 50/54] Update 007.md --- book/syntax_exercises/007.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md index cd931c0..bb12b9e 100644 --- a/book/syntax_exercises/007.md +++ b/book/syntax_exercises/007.md @@ -1,4 +1,4 @@ -# Exercise 7: File Structure (Markdown) +# Exercise 7: File structure by titles In this exercise you will learn how to structure your chapters. @@ -12,7 +12,7 @@ More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyt ``` -1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch.. When you've arrived there, click `Add file` - {octicon}`plus;1em` `Create new file`. +1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch. When you've arrived there, click `Add file` - {octicon}`plus;1em` `Create new file`. 2. Name your file and end it with the file extension `.md` (e.g. `my_new_file.md`), your filename preferable shouldn't include spaces. @@ -54,7 +54,7 @@ text 8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.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` (getting bored of waiting? Soon, 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. +9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Please not that the name of the page in the table of contents is identical to the title of the page, while the URL corresponds to the directory structure of the source files. ```{admonition} Check your understanding :class: note @@ -63,4 +63,4 @@ Before moving on to the next exercise, make sure you understand the following: - What is the correct way to define a title in a Markdown file? - How many chapter titles (`#`) are allowed in a single Markdown file? - What file type are you using? -``` \ No newline at end of file +``` From 063c886000cef1ccb2542653c1a918fdecae2bcb Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 4 Mar 2025 17:05:29 +0100 Subject: [PATCH 51/54] Update 004.md --- book/exercises/004.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/exercises/004.md b/book/exercises/004.md index 8f2c172..d08c451 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -9,8 +9,8 @@ Can you make a new branch of your book with an additional file `file_on_new_vers 1. Add a new Issue to let people know you're working on something by going to your repository - {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` 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. +4. Click `Create` +5. In the new window (inside your just created issue), 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-<your_issue_title>` to open your branch. @@ -25,4 +25,4 @@ 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 e3da25e82df99c0937e0b26fd74912a4cce4439d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 18 Mar 2025 11:08:28 +0100 Subject: [PATCH 52/54] typos --- book/credits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/credits.md b/book/credits.md index c8de8bb..4363c3f 100644 --- a/book/credits.md +++ b/book/credits.md @@ -16,7 +16,7 @@ We anticipate that the content of this book will change significantly. Therefore This book is created using open source tools: it is a JupyterBook that is written using Markdown and Jupyter notebooks. Additional tooling is used from the [TeachBooks initiative](https://teachbooks.io/) to enhance the editing and reading experience. The files are stored on a [public GitHub repository](`<link to GitHub repo>`). The website can be viewed at `<link to book website url>`. View the repository README file or contact the authors for additional information. ## License -This manual is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/) allowing you to share and adapt the material, as long as the source is named. External resources that are reused in this manual are listed below. +This book is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/) allowing you to share and adapt the material, as long as the source is named. External resources that are reused in this book are listed below. (external_resources)= ### External resources From 9121c18a7d47fd0e626a6154d6bff72f91a04828 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Thu, 20 Mar 2025 14:54:20 +0100 Subject: [PATCH 53/54] expand explanation config --- book/_config.yml | 55 +++++++++++++++++++++++------------------------- requirements.txt | 1 + 2 files changed, 27 insertions(+), 29 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index d488258..beb6e64 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,51 +1,48 @@ -Title: TeachBooks template +title: TeachBooks template #Replace this with your own book title author: TeachBooks Team, built with <a href="https://teachbooks.io">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> #add your own name here execute: - execute_notebooks: "off" + execute_notebooks: "off" #replace this if you want don't have notebooks with output and you want to add notebook output during build -only_build_toc_files: true - -html: - favicon : "figures/TB_favicon.ico" - baseurl : "https://teachbooks.io/" #Replace this with your own URL +only_build_toc_files: true #replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents sphinx: config: html_js_files: - - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js #required for live code: https://teachbooks.io/manual/features/live_code.html thebe_config: - use_thebe_lite: true - exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] + use_thebe_lite: true #required for live code: https://teachbooks.io/manual/features/live_code.html + exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code: https://teachbooks.io/manual/features/live_code.html html_theme_options: logo: - text: Template + text: Template #Replace this with your own book title image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark) image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light) repository_url: "https://github.com/user/repo" #add your own repo URL here - path_to_docs: "book" - repository_branch: "main" - use_edit_page_button: true - use_repository_button: true - use_issues_button : true + path_to_docs: "book" #required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html) + repository_branch: "main" #replace when you change the name of your published branch (required for edit_page_button) + use_edit_page_button: true #replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo) + use_repository_button: true #replace with false if you don't want the repository button (i.e. if you have a private repo) + use_issues_button : true #replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo) launch_buttons: - thebe: true - html_show_copyright: false - html_last_updated_fmt: '%B %-d, %Y' + thebe: true #required for live code: https://teachbooks.io/manual/features/live_code.html + favicon : "figures/TB_favicon.ico" #replace this with your own favicon + baseurl : "https://teachbooks.io/" #Replace this with your own URL + html_show_copyright: false #as the copyright is included in the author field + html_last_updated_fmt: '%B %-d, %Y' #adds the date of the last update to the footer html_static_path: ["figures"] # add folders that contain files that need to be included, such as the location of the logo(s) mathjax3_config: chtml: { mtextInheritFont: true # To typeset text within math prettier } - extra_extensions: - - sphinx.ext.imgconverter - - jupyterbook_patches - - download_link_replacer - - sphinx.ext.extlinks - - sphinx_image_inverter - - sphinx_iframes - - sphinx_exercise - - teachbooks_sphinx_tippy + extra_extensions: #Gives you a starter package of extensions to use in your book + - jupyterbook_patches # Patches by TeachBooks https://github.com/TeachBooks/JupyterBook-Patches + - download_link_replacer # Allows you to replace and add downloadable files to a page header https://teachbooks.io/manual/external/Download-Link-Replacer/README.html + - sphinx_image_inverter # Inverts images for dark mode https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html + - sphinx_iframes # Eases the embedding of iframes https://teachbooks.io/manual/external/sphinx-iframes/README.html + - sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/ + - teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html + - sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html bibtex_bibfiles: - - references.bib + - references.bib #required for references diff --git a/requirements.txt b/requirements.txt index 3c3ee06..fc577ed 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,6 +6,7 @@ download_link_replacer sphinx-exercise teachbooks-sphinx-tippy sphinx-iframes +sphinx-named-colors # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From 0ce05e4b6f0ae90e23fba083b0dfd09fc13ccb2d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Fri, 21 Mar 2025 12:19:28 +0100 Subject: [PATCH 54/54] Update _config.yml --- book/_config.yml | 65 ++++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 32 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index beb6e64..488fa6d 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,48 +1,49 @@ -title: TeachBooks template #Replace this with your own book title -author: TeachBooks Team, built with <a href="https://teachbooks.io">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> #add your own name here +title: TeachBooks template # Replace this with your own book title +author: TeachBooks Team, built with <a href="https://teachbooks.io">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> + # Replace TeachBooks Teams with your own name in the line above execute: - execute_notebooks: "off" #replace this if you want don't have notebooks with output and you want to add notebook output during build + execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build -only_build_toc_files: true #replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents +only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents -sphinx: +sphinx: # Options passed on to the underlying sphinx-parser config: html_js_files: - - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js #required for live code: https://teachbooks.io/manual/features/live_code.html + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code: https://teachbooks.io/manual/features/live_code.html thebe_config: - use_thebe_lite: true #required for live code: https://teachbooks.io/manual/features/live_code.html + use_thebe_lite: true # Required for live code: https://teachbooks.io/manual/features/live_code.html exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code: https://teachbooks.io/manual/features/live_code.html html_theme_options: logo: - text: Template #Replace this with your own book title - image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark) - image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light) - repository_url: "https://github.com/user/repo" #add your own repo URL here - path_to_docs: "book" #required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html) - repository_branch: "main" #replace when you change the name of your published branch (required for edit_page_button) - use_edit_page_button: true #replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo) - use_repository_button: true #replace with false if you don't want the repository button (i.e. if you have a private repo) - use_issues_button : true #replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo) + text: Template # Replace this with your own book title + image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark) + image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light) + repository_url: "https://github.com/user/repo" # Add your own repo URL here + path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html) + repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button) + use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo) + use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo) + use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo) launch_buttons: - thebe: true #required for live code: https://teachbooks.io/manual/features/live_code.html - favicon : "figures/TB_favicon.ico" #replace this with your own favicon - baseurl : "https://teachbooks.io/" #Replace this with your own URL - html_show_copyright: false #as the copyright is included in the author field - html_last_updated_fmt: '%B %-d, %Y' #adds the date of the last update to the footer - html_static_path: ["figures"] # add folders that contain files that need to be included, such as the location of the logo(s) + thebe: true # Required for live code: https://teachbooks.io/manual/features/live_code.html + favicon : "figures/TB_favicon.ico" # Replace this with your own favicon + baseurl : "https://teachbooks.io/" # Replace this with your own URL + html_show_copyright: false # As the copyright is included in the author field + html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer + html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s) mathjax3_config: chtml: { - mtextInheritFont: true # To typeset text within math prettier + mtextInheritFont: true # To typeset text within math prettier } - extra_extensions: #Gives you a starter package of extensions to use in your book - - jupyterbook_patches # Patches by TeachBooks https://github.com/TeachBooks/JupyterBook-Patches - - download_link_replacer # Allows you to replace and add downloadable files to a page header https://teachbooks.io/manual/external/Download-Link-Replacer/README.html - - sphinx_image_inverter # Inverts images for dark mode https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html - - sphinx_iframes # Eases the embedding of iframes https://teachbooks.io/manual/external/sphinx-iframes/README.html - - sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/ - - teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html - - sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html + extra_extensions: # Gives you a starter package of extensions to use in your book + - jupyterbook_patches # Patches by TeachBooks https://github.com/TeachBooks/JupyterBook-Patches + - download_link_replacer # Allows you to replace and add downloadable files to a page header https://teachbooks.io/manual/external/Download-Link-Replacer/README.html + - sphinx_image_inverter # Inverts images for dark mode https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html + - sphinx_iframes # Eases the embedding of iframes https://teachbooks.io/manual/external/sphinx-iframes/README.html + - sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/ + - teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html + - sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html bibtex_bibfiles: - - references.bib #required for references + - references.bib # Required for references