update from main

README.md

@@ -15,22 +15,22 @@ The template allows you to start your own TeachBook and hosting that TeachBook o
 
 How to use the template is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
 
-```{figure} figures/teachbooks-template.gif
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/teachbooks-template.gif?raw=true
 ---
 name: template_demo_public
 ---
 Demonstration for a public repository, video available [here](https://youtu.be/nN3Oi_MVvF0)
 ```
 
-1. To get started making your TeachBook with our functionalities, use the [template TeachBook](https://github.com/TeachBooks/template) as template:
+1. To get started making your TeachBook with our functionalities, use the [template TeachBook](https://github.com/TeachBooks/main/template) as template:
 
-```{figure} figures/use_template.png
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/use_template.png?raw=true
 :name: use-template
 ```
 
 2. Fill in a repository name, this name will be used in the future url of your book:
 
-```{figure} figures/create_new_repository.png
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/create_new_repository.png?raw=true
 :name: create_new_repository
 ```
 
@@ -40,26 +40,28 @@ Demonstration for a public repository, video available [here](https://youtu.be/n
 
 5. You need to activate GitHub pages so that your website is published to the internet. As long as you don't do this your TeachBook is not published online. Actually, now that you've taken this template our workflow tries to publish it to GitHub pages, which you didn't have the chance to activate yet. That's why you probably received an email with 'call-deploy-book: Some jobs were not successful' and you see the failed job under {octicon}`play;1em` `Actions` - `All workflows` -  `call-deploy-book` - {octicon}`x-circle-fill;1em` `Initial commit`. You can activate GitHub pages by setting the source for GitHub pages to GitHub Actions under {octicon}`gear;1em` `Settings` - {octicon}`browser;1em` `Pages` - `Build and deployment` - `Source` - `GitHub Actions`:
 
-```{figure} figures/set_up_pages.png
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/set_up_pages.png?raw=true
 :name: activate_pages
 ```
 
 6. Make an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under {octicon}`code;1em` `Code`).  Now checkout the progress of the publishing workflow under {octicon}`play;1em``Actions` - `All workflows` -  `call-deploy-book` -`<the most recent workflow run>`. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from {octicon}`play;1em``Actions` - `All workflows` -  `call-deploy-book` - {octicon}`x-circle-fill;1em` `Initial commit` - {octicon}`sync;1em` `Re-run all jobs` - `Re-run jobs`:
 
-```{figure} figures/action_re-run.jpeg
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/action_re-run.jpeg?raw=true
 :name: action
 ```
 
 7. When the workflow has finished, visit your build TeachBook at `https://<username or organiszation_name>.github.io/<repository_name>` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. These links are visible in the action's summary as well, as shown in the figure of step 4.
 
 8. Want to get started directly? Your book contains a few exercises to get your started! Visit `https://<username or organiszation_name>.github.io/<repository_name>/exercises/exercises` (case sensitive) to get started with the first ones to get the basics of how to interact with your book on GitHub.
 
-![exercises](figures/exercises.png)
-
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/exercises.png?raw=true
+:name: github_pages_as_website
+:width: 300px
+```
 Additional tip: 
 Set the repository website as your GitHub Pages website under {octicon}`code;1em` `Code`- `About` - {octicon}`gear;1em` - `Website` - `Use your GitHub Pages Website`
 
-```{figure} figures/use_github_pages_website.png
+```{figure} https://github.com/TeachBooks/template_figures/blob/main/use_github_pages_website.png?raw=true
 :name: github_pages_as_website
 ```
 

book/_config.yml

@@ -1,3 +1,4 @@
+Title: TeachBooks template
 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:
@@ -42,6 +43,8 @@ sphinx:
     - download_link_replacer
     - sphinx.ext.extlinks
     - sphinx_image_inverter
+    - sphinx_exercise
+    - teachbooks_sphinx_tippy
 
 bibtex_bibfiles: 
   - references.bib

book/credits.md

@@ -3,22 +3,33 @@
 
 You can refer to this book as:
 
-> `<editors>` (`<year>`) _`<title>`_. `<url to github repo>`
-
-The introduction, structure of the book and formatting of contents is done by the Editors. Some chapters and pages have additional primary authors who are identified within the book either at the bottom of the first page in a chapter, or at the bottom of an individual page, as necessary. If an author is not listed on a particular page, it is by the Editors.
+> `<editors>` (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`
 
 You can refer to individual chapters or pages within this book as:
 
-> `<Primary Author>` (`<date>`) `<Title of Chapter or Page>`. In `<editors>` (Ed.), _`<title>`_. `<url to github repo>`
-
-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 within the book. For example:
+> `<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`
 
-> `<Primary Author>` (`<date>`) `<Title of Chapter or Page>`. In `<editors>` (Ed.),  _`<title>`_. `<url to github repo>` (`./book/intro/` chapter, accessed November, 2024).
+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.
 
 ## How the book is made
 
 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.
+
+(external_resources)=
+### External resources
+
+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
+
+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. 
+
+
 (editor)=
 ## About the Editors
 

book/exercises.md

@@ -1,10 +1,6 @@
 # Exercises
 
-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.
-
-```{exercise}
-Work through the exercises attached to this page (you can find them in the left sidebar).
-```
+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).
 
 ```{tip}
 Maybe you're already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents. In that case, can you answer the following questions (referring to the exercises):

book/exercises/001.md

@@ -2,7 +2,9 @@
 
 Let's start with the most basic edit: add some text to a file and see that the website is updated.
 
-> Can you add some content to the intro page?
+::::::{topic} Exercise objective
+Can you add some content to the intro page?
+::::::
 
 1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com/<your_username>/<your_repo_name>`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file`
 2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this!
@@ -13,14 +15,17 @@ Let's start with the most basic edit: add some text to a file and see that the w
 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!).
 
-```{admonition} Check your understanding
-:class: note
+```{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)
 
-Before moving on to the next exercise, make sure you understand the following:
-- Where are the contents of the book stored?
-- How can you edit a single file via the GitHub browser interface?
-- What is a commit and what role does it play in the editing process?
-- Given a specific GitHub repository, can you determine the URL of the book website?
-- How can you view the changes you made to the book?
-- What is the purpose of a commit message and description?
-```
+[Or watch the video here](https://youtu.be/gn1zBmmunco)
+```
+
+:::{card} Check your understanding
+<iframe src="https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=2" width="624" height="324" frameborder="0" allowfullscreen="allowfullscreen" title="Testing your knowledge"></iframe><script src="https://home.teachbooks.io/wp-content/plugins/h5p/h5p-php-library/js/h5p-resizer.js" charset="UTF-8"></script>
+:::
+
+:::{card} Check your understanding
+<iframe src="https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=1" width="959" height="502" frameborder="0" allowfullscreen="allowfullscreen" title="Testing more Teachbooks knowledge"></iframe><script src="https://home.teachbooks.io/wp-content/plugins/h5p/h5p-php-library/js/h5p-resizer.js" charset="UTF-8"></script>
+:::

book/exercises/002.md

@@ -2,11 +2,13 @@
 
 Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet!
 
-> Can you add the file named `file_to_be_added_to_toc.md` to the book website?
+::::::{topic} Exercise objective
+Can you add the file named `file_to_be_added_to_toc.md` to the book website?
+::::::
 
 1. Go to the {octicon}`code;1em` `Code` - `Book` directory of your GitHub repository and find the location of `file_to_be_added_to_toc.md`
 2. Go to the the file `book/_toc.yml` on your GitHub repository - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file`
-3. Add `file_to_be_added_to_toc.md` as a second item in the `Some content` chapter
+3. Add `file_to_be_added_to_toc.md` as a second subpage under `some_content/overview.md`. `some_content/text_and_code.ipynb` is the first subpage.
 
 ````{admonition} Need some help?
 :class: tip, dropdown

book/exercises/003.md

@@ -2,7 +2,9 @@
 
 As we've added some content by now, let's make this book a bit more personal! We'll make some changes to the `_config.yml` file which changes the configuration of the book website. 
 
-> Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
+::::::{topic} Exercise objective
+Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
+::::::
 
 1. Go to the the file `book/_config.yml` on your GitHub repository - {octicon}`code;1em` `Code` - `Book` - `_config.yml` - {octicon}`pencil;1em` `Edit this file`
 2. In the `Edit` field, change the author which will be shown in the footer of the book website.

book/exercises/004.md

@@ -2,7 +2,9 @@
 
 By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml`. But what if you want to make some changes but don't want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let's try and do that! Later on, you'll probably want to merge your newest version back into the original book. That's what we'll do in [](./005.md).
 
-> Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
+::::::{topic} Exercise objective
+Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
+::::::
 
 1. Add a new Issue to let people know you're working on something by going to your repository - {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`

book/exercises/005.md

@@ -2,7 +2,9 @@
 
 In [](./004.md) you created your own version of a book. But it would be a pity if you never contribute back to the original book right? Probably your additions are very useful there too! You'll merge you version of the book which is stored on a branch into the original book which is on main. If there've been some changes on that main branch in the meantime, git will take care of that!
 
-> Can you merge your branch into `main` with a pull request?
+::::::{topic} Exercise objective
+Can you merge your branch into `main` with a pull request?
+::::::
 
 1. Go to your repository homepage. Probably, it will have big yellow announcement saying {octicon}`git-branch;1em` `1-<your_issue_title> had recent pushes <some> minutes ago - Compare & Pull request`. We'll ignore that for now and do it manually.
 2. Go to the pull request page on your repository homepage - {octicon}`git-pull-request;1em` and click `New pull request`

book/exercises/006.md

@@ -10,7 +10,9 @@ So far you did everything on your own, within a single repository. However, book
 The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository.
 ```
 
-> Can you fork a book repository of someone else, make changes and contribute back?
+::::::{topic} Exercise objective
+Can you fork a book repository of someone else, make changes and contribute back?
+::::::
 
 ```{tip}
 This part describes how you can make a change in the book of someone else.

book/exercises/summary.md

@@ -2,7 +2,7 @@
 
 With the exercises, you did all the steps of our TeachBooks workflow!
 
-```{figure} ../figures/TeachBooks_flowchart.svg
+```{figure} https://github.com/TeachBooks/logos_and_visualisations/blob/main/TB_flowchart/TeachBooks_flowchart.svg?raw=true
 ---
 width: 500px
 align: center