Merge branch 'main' into 'Inspiring-Examples'

# Conflicts:
#   book/_toc.yml

.gitmodules

@@ -7,3 +7,9 @@
 [submodule "book/external/deploy-book-workflow"]
 	path = book/external/deploy-book-workflow
 	url = https://github.com/TeachBooks/deploy-book-workflow.git
+[submodule "book/external/latex-to-markdown-conversion"]
+	path = book/external/latex-to-markdown-conversion
+	url = https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion.git
+[submodule "book/external/Useful_python_code"]
+	path = book/external/Useful_python_code
+	url = https://github.com/TeachBooks/Useful_python_code.git

README.md

@@ -4,6 +4,6 @@ A short introduction to Git, VSCode and Jupyter Books for teachers and TA's. Cur
 
 ## Contributing
 
-Feedback is always welcome. If something doesn't work, or if you have suggestions, you can always make an issue on the Issue Board or make a Merge Request.
+Feedback is always welcome. If something doesn't work, or if you have suggestions, you can always make an issue on the Issue Board or make a Merge Request. If you create a branch, that branch will also be visible on the mirrored repository on GitHub to ease reviewing: https://github.com/TeachBooks/mirror_teachbook_manual/actions
 
 If you've questions, contact Tom van Woudenberg, Robert Lanzafame or our TAs Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)

book/_config.yml

@@ -6,6 +6,8 @@ logo: images/Logo_without_background.png
 execute:
   execute_notebooks: 'off'
 
+only_build_toc_files: true
+
 html:
   favicon : "images/favicon.ico"
   baseurl  : "https://teachbooks.tudelft.nl/jupyter-book-manual/"

book/_toc.yml

@@ -61,7 +61,6 @@ parts:
           - file: features/jupyterlite/configuration
           - file: features/jupyterlite/including-jupyterlite
 
-
   - caption: Examples
     chapters:
     - file: examples/overview
@@ -70,6 +69,20 @@ parts:
     - file: examples/live_code.md
     - file: examples/example_gumbel.ipynb
     - file: examples/theory_questions.md
-    - file: examples/example_quiz_interactive.ipynb
+    - file: examples/interactive_templates.md
-    - file: examples/coding_theory_widgets.ipynb
+      sections:
-    - file: examples/parametric_questions.ipynb
+      - file: examples/example_gumbel.ipynb
+      - file: examples/example_quiz_interactive.ipynb
+      - file: examples/coding_theory_widgets.ipynb
+      - file: examples/parametric_questions.ipynb
+
+  - caption: Editing tools
+    chapters:
+    - file: tools/figmaker
+    - file: helper_code/intro.md
+      sections:
+      - file: external/latex-to-markdown-conversion/README.md
+      - file: external/Useful_python_code/snippit.ipynb
+      - file: external/Useful_python_code/extensionfildownloadreturn.ipynb
+      - file: external/Useful_python_code/figshrinker.ipynb
+       

book/basic-features/References.md

@@ -2,6 +2,24 @@
 
 To make references to figures, equations et cetera, use the following syntax:
 
-- For figures, use: ``{numref}`<name of the figure>` ``
+- For figures, use: ``{numref}`Figure {number} <name of the figure>` ``
 - For equations, use: ``{eq}`<equation label>` ``
 - For citations, use: ``{cite:p}`<bibtex_entry>` `` for a citation between parenthesis, or ``{cite:t}`<bibtex_entry>` `` for an inline citation.
+
+**Examples**
+
+Using ``{numref}`Figure {number} <fig-gitpush>` `` produces the output: {numref}`Figure {number} <fig-gitpush>`. 
+```{figure} ../images/git-push.png
+---
+width: 50%
+name: fig-gitpush
+---
+Some caption here
+```
+
+Or, the derivation results in equation {eq}`<eq:Newton>`.
+
+$$ F = m\cdot a $$(eq:Newton)
+
+
+

book/basic-features/equations.md

@@ -14,6 +14,12 @@ $$
     F = m \cdot a
 $$
 
+```{tip}
+The scientific rules dictate that quantities ($F$, $m$, $a$ etc.) should be printed in italics. Units, however, should not! One can use `\text{m}` in an equation to comply to this rule:
+
+$$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}
+```
+
 > **Warning**
 > 
 > Make sure there is a blank line *before* the display mode equations, otherwise it will render as inline and display the outer set of $$$ symbols. Also, the Euro symbol is not included in MathJax (see note below) and must be specified using `\unicode{0x20AC}` (note that it displays incorrectly in some Markdown renderers like VS Code).
@@ -24,6 +30,12 @@ To number the equations and refer in text, you need to provide a label to the eq
         F = m \cdot a
     $$ (newtons_second_law)
 
+Resulting in:
+
+$$
+    F = m \cdot a
+$$ (newtons_second_law)
+
 > **Note**
 > 
 > The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).

book/basic-features/figures.md

@@ -131,13 +131,3 @@ name: demoexample4
 example 4:including figclass: margin
 ```
 
-## Figure syntax maker
-One might quickely forget the code for making figures, here is a useful tool to make your figures, just specify all information and the code is produced for you:
-
-<div id="figuur_formulier">
-
-</div>
-<div id="listContainer">
-  
-</div> 
-

book/basic-features/jupyterbook.md

@@ -7,7 +7,7 @@ To build a Jupyter Book, you need three things:
 3. Content
 
 ## The configuration file
-The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book.  Here is a basic example of a configuration file, taken from this book:
+The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
 
 ```yml
 title: Jupyter Book Manual
@@ -84,3 +84,31 @@ parts:
 
 et cetera...
 ```
+
+## The structure of a chapter
+The 'nested' structure in the TOC is one way to organize your book. Another way to do so is in the file itself. The structure is defined by the number of `#`:
+
+```
+# Chapter 1 title
+
+## Section 1.1 
+
+### Subsection 1.1.1 
+
+## Section 1.2 
+
+### Subsection 1.2.1
+```
+
+The depth for numbered subsection can be set in the TOC file: 
+
+```
+parts:
+- caption: Part 1
+  numbered: 2
+  chapters:
+  - file: chapter_1
+    sections:
+    - file: section_1_1
+    - file: section_1_2
+```

book/basic-features/overview.md

@@ -2,7 +2,7 @@
 
 ```{admonition} User types
 :class: tip
-This section is useful for user type 3-6.
+This section is useful for user type 3-5.
 ```
 
 A short description on basic features is given here:

book/external/Useful_python_code

@@ -0,0 +1 @@
+Subproject commit c8327b3e2cc68d44958974a47c940bc89f4bb32b

book/external/deploy-book-workflow

@@ -1 +1 @@
-Subproject commit d5eab25a29e2cc558ec449577dab669c02758a11
+Subproject commit 081491b5f7bd0beecb5663228eaf5ab80b9dd57c

book/external/latex-to-markdown-conversion

@@ -0,0 +1 @@
+Subproject commit 0b9b6512da9ff9011e56897eb6837cc3ed89ee45

book/external/template

@@ -1 +1 @@
-Subproject commit 1d033396e8e38bb203c2db8210e5501b7099fcb1
+Subproject commit 2d5513da0a53b606f870890237ef4417dc18b398

book/helper_code/intro.md

@@ -0,0 +1,10 @@
+# Scripts for automating workflow
+
+This chapter contains a few scripts which can be useful in the book-editing process:
+ - [LaTeX to markdown conversion](../external/latex-to-markdown-conversion/README.md) to convert a LaTeX file into jupyter-book compatible markdown.
+ - [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder. 
+ - [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder. 
+ - [Extensionchecker](extensionchecker) to identify the kind of files present in subfolder
+ - [Filedownloader](filedownloader) to return the downloadlink for markdown for all files with a specified extension
+ - [Figreturner](figreturner) to return the markdown code for a figure in a specific extension
+ - [Figshrinker](../external/Useful_python_code/figshrinker.ipynb) to compress JPEG images.

book/installation-and-setup/organize-team.md

@@ -19,12 +19,14 @@ If you want to create a collaborative book for students, there's a few agreement
 
 ## Tools
 - Choose between GitHub and GitLab, as explained below
+- Choose whether to host your git repository in your private account or from a share teams (groups in GitLab, organization in GitHub). For GitHub this influences your book web url as well, as it hold your username or organization name. For courses we therefore advise you to create a organization with the course name. Furthermore, on GitHub a private repository has a limited amount of actions-minutes required for published your book. On GitLab, the choice for private or public doesn't influence your web url and the amount of computing power available as that requires you to set up a server yourself.
+- Choose whether to have your git repository public or private (independent of whether your book website is public or private). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)). If you've a organization for your book on github, link your GitHub team rights to your organization as described on the [github website](https://github.com/team#organizations)
 - If you've chosen for GitHub, start with our [template](../external/template/README.md)
 - Define branches in GitHub/GitLab. We advise the following branches:
-  - A published branch which contains the students' version of this year. This could be called ie. `publish` or `main` or `<current acadamic year>`
+  - A published branch which contains the students' version of this year. This could be called ie. `publish` or `main` or `<current acadamic year>`. Add this branch as the `PRIMARY BRANCH` when making use of the [github workflow](gh-workflow-settings), this will make sure students are redirected to this URL which doesn't move when adding new versions of the book later on. If you plan on keeping only one public version, it's advised to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy` which makes sure the primary branch is copied to root so that the URL is compact.
-  - A development branch which contains all the new content combined but not yet published to students. This could be called `dev` or `main` (depending on whether you prefer having the most recent published version as main or the development branch).
+  - A development branch which contains all the new content combined but not yet published to students. This could be called ie. `dev` or `main`. `dev` is advised when  you prefer git's default branch to be the most recent published version (as `main` is expected to be the default branch by many).
-  - Branches which will be created during the editing process which contain edits ie. single chapters
+  - Branches which will be created during the editing process, which is probably something which you want to allow. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches are build and your fellow editors can review their own and each other's versions online. Once every while, it doesn't hurt to go through the list of branches and delete any branches which are merged but not deleted.
-  - Branches for previous study years which contain each year's version of the book. These could be called `<academic year>`
+  - (future) branches for previous study years which contain each year's version of the book. These could be called `<academic year>` which ends up in their url too. Add these branches to the list of `BRANCHES_ARCHIVED` when making use of the [github workflow](gh-workflow-settings) to add a banner to the page indicating it's archived state.
 - Setup protected branches in GitHub/GitLab to prevent accidental changes
 - Add people with GitHub/GitLab permission matching their role and the protected branches.
 - Add a readme explaining the way you organized branches and permissions

book/installation-and-setup/user_types.md

@@ -1,6 +1,6 @@
 # User types
 
-Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 6 types of users.
+Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
 
 1. **Students providing feedback on the published website**.<br>  <img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 10px;"> There are multiple tools of providing feedback in the built book:  a) using the issue button in the top-right corner to directly create issues visible to the editor team. b) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which     allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html). c) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle.
 

book/intro.md

@@ -3,6 +3,11 @@
 This is an introduction to Git, VS Code and Jupyter Books for teachers and teaching assistants involved in TeachBooks, our platform easing the process of making a <a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. This book is still work in progress, so feel free to contribute https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual! For more information about teachbooks, visit [https://teachbooks.tudelft.nl/](https://teachbooks.tudelft.nl/).
 
 ## Contact
-If you encounter any issues and you've a TU Delft account, report it by clicking  <svg class="svg-inline--fa fa-gitlab" aria-hidden="true" focusable="false" data-prefix="fab" data-icon="gitlab" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" data-fa-i2svg=""><path fill="currentColor" d="M503.5 204.6L502.8 202.8L433.1 21.02C431.7 17.45 429.2 14.43 425.9 12.38C423.5 10.83 420.8 9.865 417.9 9.57C415 9.275 412.2 9.653 409.5 10.68C406.8 11.7 404.4 13.34 402.4 15.46C400.5 17.58 399.1 20.13 398.3 22.9L351.3 166.9H160.8L113.7 22.9C112.9 20.13 111.5 17.59 109.6 15.47C107.6 13.35 105.2 11.72 102.5 10.7C99.86 9.675 96.98 9.295 94.12 9.587C91.26 9.878 88.51 10.83 86.08 12.38C82.84 14.43 80.33 17.45 78.92 21.02L9.267 202.8L8.543 204.6C-1.484 230.8-2.72 259.6 5.023 286.6C12.77 313.5 29.07 337.3 51.47 354.2L51.74 354.4L52.33 354.8L158.3 434.3L210.9 474L242.9 498.2C246.6 500.1 251.2 502.5 255.9 502.5C260.6 502.5 265.2 500.1 268.9 498.2L300.9 474L353.5 434.3L460.2 354.4L460.5 354.1C482.9 337.2 499.2 313.5 506.1 286.6C514.7 259.6 513.5 230.8 503.5 204.6z"></path></svg> --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual).
+If you encounter any issues and you have a TU Delft account, report it by clicking  <svg class="svg-inline--fa fa-gitlab" aria-hidden="true" focusable="false" data-prefix="fab" data-icon="gitlab" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" data-fa-i2svg=""><path fill="currentColor" d="M503.5 204.6L502.8 202.8L433.1 21.02C431.7 17.45 429.2 14.43 425.9 12.38C423.5 10.83 420.8 9.865 417.9 9.57C415 9.275 412.2 9.653 409.5 10.68C406.8 11.7 404.4 13.34 402.4 15.46C400.5 17.58 399.1 20.13 398.3 22.9L351.3 166.9H160.8L113.7 22.9C112.9 20.13 111.5 17.59 109.6 15.47C107.6 13.35 105.2 11.72 102.5 10.7C99.86 9.675 96.98 9.295 94.12 9.587C91.26 9.878 88.51 10.83 86.08 12.38C82.84 14.43 80.33 17.45 78.92 21.02L9.267 202.8L8.543 204.6C-1.484 230.8-2.72 259.6 5.023 286.6C12.77 313.5 29.07 337.3 51.47 354.2L51.74 354.4L52.33 354.8L158.3 434.3L210.9 474L242.9 498.2C246.6 500.1 251.2 502.5 255.9 502.5C260.6 502.5 265.2 500.1 268.9 498.2L300.9 474L353.5 434.3L460.2 354.4L460.5 354.1C482.9 337.2 499.2 313.5 506.1 286.6C514.7 259.6 513.5 230.8 503.5 204.6z"></path></svg> --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual).
 
-If you've questions, contact Tom van Woudenberg, Robert Lanzafame or our TAs Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)
+If you have questions, contact Tom van Woudenberg, Robert Lanzafame or our TA Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)
+
+## Feedback
+We really value your feedback on this manual so we can keep improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
+
+Happy book building!

book/tools/figmaker.md

@@ -0,0 +1,15 @@
+# Figure syntax maker
+
+```{admonition} User types
+:class: tip
+This section is useful for user type 3-5.
+```
+
+One might quickely forget the code for making figures, here is a useful tool to make your figures, just specify all information and the code is produced for you:
+
+<div id="figuur_formulier">
+
+</div>
+<div id="listContainer">
+  
+</div> 

book/workflows/branches.md

@@ -48,7 +48,7 @@ The circled menu is the branch selection menu.
 
 ``````{tab-item} ... GitHub
 
-How to branch is demonstrated in the figure below, followed by a step-by-step tutorial.
+How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
 
 ```{figure} figures/branching-github-ezgif.com-optimize.gif
 ---

book/workflows/edit_book.md

@@ -49,6 +49,15 @@ You can edit it and commit the changes in the same manner as with markdown (.md)
 ````
 ````{tab-item} ... GitHub
 
+How to make an edit and make a commit is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
+ 
+```{figure} figures/user3-collaboration.gif
+---
+name: user3_edit_demo
+---
+Demonstration, video available [here](https://youtu.be/LG1vzrOLQHA)
+```
+
 In GitHub, you can directly make changes in the files on the remote repository. You can make changes to the files already in the repository using the text editor but you can also upload new files!
 
 1. Navigate to the repository you want to work in and make sure you're in the correct branch.
@@ -100,6 +109,14 @@ You can edit it and commit the changes in the same manner as with markdown (.md)
 `````{tab-set}
 ````{tab-item} ... Git in VS Code
 
+How to make an edit and make a commit using VS Code is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
+ 
+```{figure} figures/User4_updated-ezgif.com-optimize.gif
+---
+name: user4_clone_edit_demo
+---
+Demonstration, video available [here](https://youtu.be/bThimdDRXTc)
+
 1. Make some changes to a file in for example VS Code and save them.
 
 2.  Select the files ready to be added to Git-timeline (staging) 
@@ -290,6 +307,14 @@ Alternatively, you can also click on `Push origin` in the top bar.
 `````{tab-set}
 ````{tab-item} ... Git in VS Code
 
+The steps above are demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
+ 
+```{figure} figures/User5_wholeshabang-ezgif.com-optimize.gif
+---
+name: user5_demo
+---
+Demonstration, video available [here](https://youtu.be/2ttjBevkEP8)
+
 1. Make some changes to a file in for example VS Code and save them.
 
 2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! 

dummy.txt

@@ -0,0 +1 @@
+dummy