Merge branch 'main' into CollaborationGit

.gitlab-ci.yml

@@ -8,6 +8,7 @@ variables:
   REGISTRY_HOST: localhost:5000
   TAG_LATEST: $REGISTRY_HOST/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME:latest
   TAG_DRAFT: $REGISTRY_HOST/$CI_PROJECT_NAME-draft/$CI_COMMIT_REF_NAME:latest
+  GIT_SUBMODULE_STRATEGY: recursive # For submodules  
 
 cache:
   paths:
@@ -72,4 +73,4 @@ deploy-draft:
     - docker run -d --restart always -p 8018:8000 --name $CI_PROJECT_NAME-draft $TAG_DRAFT
   environment:
     name: draft
-    url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft
+    url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "book/external/Nested-Books"]
+	path = book/external/Nested-Books
+	url = https://github.com/TeachBooks/Nested-Books.git
+[submodule "book/external/template"]
+	path = book/external/template
+	url = https://github.com/TeachBooks/template.git
+[submodule "book/external/deploy-book-workflow"]
+	path = book/external/deploy-book-workflow
+	url = https://github.com/TeachBooks/deploy-book-workflow.git

book/_config.yml

@@ -1,12 +1,18 @@
-title: Intro to Git, VS Code and Jupyter Books
-author: Caspar Jungbacker
-logo: images/TUDelft_logo_rgb.png
+title: TeachBooks Manual
+author: <a href="https://teachbooks.tudelft.nl/">TeachBooks Team</a>, built with <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/?ref=chooser-v1" 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?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1" alt="">
+
+logo: images/Logo_without_background.png
 
 execute:
   execute_notebooks: 'off'
 
-launch_buttons:
-  thebe: true
+html:
+  favicon : "images/favicon.ico"
+  baseurl  : "https://teachbooks.tudelft.nl/jupyter-book-manual/"
+# START DRAFT
+  comments:
+    hypothesis: true
+# END DRAFT
 
 sphinx:
   extra_extensions:
@@ -21,4 +27,11 @@ sphinx:
     - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
     thebe_config:
       use_thebe_lite: true
-      exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"]
+      exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"]
+    html_theme_options:
+      repository_url: "https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual"
+      use_repository_button: true
+      use_issues_button : true
+      launch_buttons:
+          thebe: true
+    html_show_copyright: false

book/_toc.yml

@@ -6,6 +6,7 @@ parts:
     chapters:
     - file: installation-and-setup/user_types
     - file: installation-and-setup/git
+    - file: installation-and-setup/choose_platforms.md
     - file: installation-and-setup/overview
       sections:
       - file: installation-and-setup/vscode-setup
@@ -13,7 +14,7 @@ parts:
       - file: installation-and-setup/anaconda
       - file: installation-and-setup/git_bash_conda_vs-code.md
       - file: installation-and-setup/jupyter-book-setup
-    - file: workflows/githubtemplate
+    - file: external/template/README.md
     - file: workflows/collaboration
       sections:
       - file: workflows/milestones_issues
@@ -27,12 +28,15 @@ parts:
     - file: basic-features/overview
       sections:
       - file: basic-features/recipes.md
-      - file: installation-and-setup/extension
+      - file: basic-features/hypothesis
+      - file: basic-features/utterances
     - file: features/overview
       sections:
+      - file: external/deploy-book-workflow/README.md
       - file: features/remove_from_publish
       - file: features/custom_toc.md
       - file: features/custom_download.md
+      - file: external/Nested-Books/README.md
       - file: features/interactive_element.ipynb
         sections:
         - file: features/grasple.md

book/basic-features/hypothesis.md

@@ -0,0 +1,50 @@
+# Making comments on the website: Hypothesis
+
+Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension.
+
+```{admonition} Be careful of changing website URL's!
+:class: warning
+
+Annotations created using the Hypothesis feature are linked to the specific URL of a website, so keep this in mind if you move a book, or change the file name, as you could lose track of your work! Note that while changing the URL may make a page invisible, you can still find the annotations using the _View group activity_ feature.
+
+For example, if there is no annotation visible on this page, the URL probably changed!
+```
+
+## Set up Hypothesis in your book
+Add this to `_config.yml`. Need to create an account.
+
+```
+html:
+  comments:
+    hypothesis: true
+```
+## Using Hypothesis
+
+In this case it is easier to learn by doing! Hypothesis has been enabled for this book, but only in the _draft_ version. 
+
+````{admonition} How to View the Draft Site
+:class: tip, dropdown
+You can access the draft version by adding `draft/` at the end of the main book (but before the current page). For example:
+
+```
+https://teachbooks.tudelft.nl/jupyter-book-manual/draft/basic-features/hypothesis.html
+```
+
+You can find out more about the draft and publish feature on {ref}`this page <publish_students>`.
+````
+
+Once on the draft version of this page, look at the top right corner: you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension and allow you to view the annotations. Create an account and log in if you would like to reply or make your own annotations. You can also highlight text, but this is not publicly visible, it is only for your own reference.
+
+Note that the annotations are only visible for the page that you are currently viewing. You can see all the Annotations on a website by opening the "Public" menu at the top of the dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`).
+
+```{admonition} Tips
+:class: tip
+
+- use the {ref}`remove_from_publish` feature to enable Hypothesis in the draft book only
+```
+
+## Student-controller with browser extension
+As an alternative to activating this for everyone, you can also advise your students to use the [hypothesis browser extension](https://web.hypothes.is/start/). In this way, students are not distracted by potential unnecessary public annotation and comments by fellow students and teachers.
+
+% THIS IS ADDED TO PAGE AS ANNOTATION:
+% This is an example Annotation. Note that annotations are publicly visible, but you must create an account and be logged in to reply or make your own. You can make highlights, but they are only visible to you, not everyone. You can also see all the Annotations on a website by opening the "Public" menu at the top of this dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`).

book/basic-features/overview.md

@@ -7,7 +7,7 @@ This section is useful for user type 3-6.
 
 ```{warning} Under Construction!
 
-This page will provide a list of some commonly used book features which are all available in the original jupyter book package. However, this page includes best-practises on how to use them.
+This page will provide a list of some commonly used book features which are all available in the original <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> package. However, this page includes best-practises on how to use them.
 ```
 
 Things to include somewhere:

book/basic-features/utterances.md

@@ -0,0 +1,25 @@
+# Discussions in your book: Utterances
+
+[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
+
+The [utterances website](https://utteranc.es/) clearly explains the required steps. One thing to take care of is how you want to do the issue-mapping with respect to multiple deployed versions (draft version, student version, archived versions):
+ 
+ - `Issue title contains page pathname`/`Issue title contains page URL` is useful if you want to isolate the comments on each of the branches.
+ - `Issue title contains page title` is useful if you want to show the all comments on all different branches.
+
+The given script can be added anywhere in your book, just copy the html-script into your `.md`-file or a markdown cell in your `.ipynb`-file. The blogpost is not visible when you do a local build of the book, build it online or use a local python server as shown in {ref}`setup-local-server`.
+
+Users need to have a GitHub-account to post a message. Although this might be a burden, it allows students to track their previous posts and set up notifications on follow-up posts.
+
+If you'd like notifications on new posts in your book, which end up as issues in your GitHub repository, you can configure the GitHub `watch` settings to do so as [explained here](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).
+
+Below you see an example of this feature!
+
+## Example discussion
+<script src="https://utteranc.es/client.js"
+        repo="TeachBooks/utterances_manual"
+        issue-term="pathname"
+        theme="github-light"
+        crossorigin="anonymous"
+        async>
+</script>

book/external/Nested-Books

@@ -0,0 +1 @@
+Subproject commit 324e657ae2261761677e4b0c72256e1e85685ad2

book/external/deploy-book-workflow

@@ -0,0 +1 @@
+Subproject commit 32e1eb8725fe4c63612a13f7467491cc9765d95e

book/external/template

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

book/features/HTML_javascript.md

@@ -1,5 +1,10 @@
 # Interactive HTML/JavaScript elements
 
+```{admonition} User types
+:class: tip
+This section is useful for user type 5.
+```
+
 In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
 
 This could be for example interactive 3d figures:

book/features/adding_HTML_elements.md

@@ -25,7 +25,7 @@ What does this code do? In HTML, certain active parts of the code are defined as
 
 Let's take a closer look at the source. Since this project uses a local file structure, we can make use of relative paths such as `../_static/element_render box.html`. What does this path do? In this project, the markdown file for this article is located in the directory `book/features/adding_HTML_elements.md`. The HTML element we want to embed is located in the directory `book/_static/element_render_box.html`. The relative path thus works as follows: 
  - We start in the markdown file's directory `book/features/adding_HTML_elements.md`
- - The string `"../"` tells the iframe to move up one folder to `book`
+ - The string `"../"` tells the iframe to move up one folder to `book`. If you need to move up more subdirectories, use it recursively, eg. `../../` moves up two directories.
  - The following string `"_static/"` tells the iframe to navigate into the `_static` folder. We are now in `book/_static/`.
  - Finally, the string `"element_render_box.html"` selects the HTML file we want to embed. We are now in `book/_static/element_render_box.html`.
 

book/features/creating_basic_HTML_elements.md

@@ -1,20 +1,7 @@
 # Creating basic interactive HTML/JavaScript elements
 
-## Embedding HTML files
-A straightforward way to create interactive web-based elements is to code them directly using HTML with JavaScript. This allows us to build elements such as the one below, which shows the connection between a probability density function (pdf) and the associated cumulative density function (cdf):
-
 <iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>
 
-If we want to embed such figures in the teachbook, you can do so via an iframe which references a html file in the _static folder:
-
-```html
-<iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>
-```
-
-Here, the src path moves up one subdirectory, then enters the `_static` folder, and loads the `element_pdf_and_cdf.html` file. So how do we create this figure?
-
-## Creating a basic interactive HTML/JavaScript element
-
 At the bottom of this page, I will provide the full code for the interactive element above. In this section, let us go through the code one piece at a time. Let us begin from the top.
 
 In the first line, we specify that this file is a HTML file. In the header (`<head>`), we can load packages we need later on. Within the `<script>` tags, we are loading three different libraries from web servers: `math.js`, which provides functions for basic mathematical operations (similar to Python's `numpy` library), as well as two versions of the library `d3.js`, which contains many extremely useful functions for web interactivity.

book/features/custom_download.md

@@ -2,7 +2,7 @@
 
 ```{admonition} User types
 :class: tip
-This section is useful for user type 4-6.
+This section is useful for user type 4-5.
 ```
 
 You can control the download option of the book in two ways:

book/features/custom_toc.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 new feature is added to enable testing of all interactive features on the web server (i.e., in the draft book) while preventing students from seeing it. Pages in the draft book (`main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish` is made using a tag `REMOVE-FROM-PUBLISH`. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. The tag is applied as follows:

book/features/grasple.md

@@ -1,5 +1,10 @@
 # Grasple questions
 
+```{admonition} User types
+:class: tip
+This section is useful for user type 3-5.
+```
+
 [Grasple](https://app.grasple.com/) gives you an embed code for each exercise which looks like this, which can be added cirectly to your markdown-file.
 ```html
 <iframe height="560" src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" title="Grasple Exercise 79907" width="100%" allow="clipboard-read; clipboard-write"></iframe>

book/features/h5p.md

@@ -1,5 +1,10 @@
 # Adding interactive h5p elements
 
+```{admonition} User types
+:class: tip
+This section is useful for user type 3-5.
+```
+
 ## Instruction
 H5p elements are interactive HTML-blocks which can be imbeded in a Jupyter Book using an iframe. H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file:
 

book/features/live_code.ipynb

@@ -36,8 +36,14 @@
     "--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple\n",
     "sphinx-thebe ~= 0.9.9\n",
     "```\n",
+    "\n",
     "This will download the correct version of the sphinx extension when the book is build on the server (which loads the required packages from `requirements.txt`)\n",
     "\n",
+    "If you want to build the book locally, you need to install this version of sphinx-thebe in your environment as well with:\n",
+    "```\n",
+    "pip install -r requirements.txt\n",
+    "```\n",
+    "\n",
     "Afterwards, this sphinx extension needs to be enabled in your book. This can be done by adding the following lines to `_config.yml`:\n",
     "\n",
     "```\n",

book/images/logo-wide.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460.57 104.67"><defs><style>.cls-1{fill:#616161;}.cls-2{fill:#f37726;}</style></defs><title>logo-wide</title><path class="cls-1" d="M281.94,79.3a14.43,14.43,0,0,1-6.71-1.47,12.62,12.62,0,0,1-4.73-4.36l-.66,5.07h-6.2V27.32l-5.94-1V21.68h13.13V43.76a12.27,12.27,0,0,1,4.61-4,14,14,0,0,1,6.42-1.39A13.29,13.29,0,0,1,290.19,41a16.56,16.56,0,0,1,5.29,7.42,30.78,30.78,0,0,1,1.85,11.12v.75a25,25,0,0,1-1.85,10,15.19,15.19,0,0,1-5.29,6.65A14.08,14.08,0,0,1,281.94,79.3Zm-1.83-5.83q5.07,0,7.53-3.6t2.47-9.57v-.75a26.4,26.4,0,0,0-1.1-8,11.71,11.71,0,0,0-3.32-5.4,8.2,8.2,0,0,0-5.65-2,9.48,9.48,0,0,0-5.59,1.61,11.39,11.39,0,0,0-3.62,4.3V67.52a11.22,11.22,0,0,0,3.65,4.35A9.63,9.63,0,0,0,280.11,73.47ZM322,79.3a16.31,16.31,0,0,1-15.53-9.67,24,24,0,0,1-2.14-10.37v-.8a24,24,0,0,1,2.14-10.38A17,17,0,0,1,312.57,41a17,17,0,0,1,24.87,7.11,23.79,23.79,0,0,1,2.16,10.39v.8a24,24,0,0,1-2.16,10.4A16.15,16.15,0,0,1,322,79.3Zm0-5.61a8.83,8.83,0,0,0,5.75-1.87,11.64,11.64,0,0,0,3.5-5.14,21.67,21.67,0,0,0,1.19-7.42v-.8A21.63,21.63,0,0,0,331.24,51a11.36,11.36,0,0,0-3.53-5.14,9.81,9.81,0,0,0-11.55,0,11.31,11.31,0,0,0-3.5,5.14,22.15,22.15,0,0,0-1.15,7.42v.8a22.19,22.19,0,0,0,1.15,7.42,11.43,11.43,0,0,0,3.52,5.14A9,9,0,0,0,322,73.69Zm42.25,5.61a16.31,16.31,0,0,1-15.53-9.67,24,24,0,0,1-2.14-10.37v-.8a24,24,0,0,1,2.14-10.38A17,17,0,0,1,354.82,41a17,17,0,0,1,24.87,7.11,23.79,23.79,0,0,1,2.16,10.39v.8a24,24,0,0,1-2.16,10.4,16.15,16.15,0,0,1-15.45,9.64Zm0-5.61A8.83,8.83,0,0,0,370,71.82a11.64,11.64,0,0,0,3.5-5.14,21.67,21.67,0,0,0,1.19-7.42v-.8A21.63,21.63,0,0,0,373.49,51,11.36,11.36,0,0,0,370,45.9a9.81,9.81,0,0,0-11.55,0,11.31,11.31,0,0,0-3.5,5.14,22.15,22.15,0,0,0-1.15,7.42v.8a22.19,22.19,0,0,0,1.15,7.42,11.43,11.43,0,0,0,3.52,5.14A9,9,0,0,0,364.24,73.69Zm22.06,4.85v-4.6l5.95-1V27.32l-5.95-1V21.68h13.12V72.93l5.94,1v4.6Zm25.34,0v-4.6l4-.47-.11-.15L404.13,58.6l3.71-5.72,15.94,20.19,5.69.87v4.6ZM398.92,67.13l-2.67-5.66,17.14-17.06.17-.22-4.22-.47V39.1h17v4.62l-5.06,1Z"/><path class="cls-2" d="M255.8,104.69q-10.41-2.94-14.82-9.35a26.7,26.7,0,0,1-4.4-15.48V68.92q0-6-2.74-9.31t-8.37-3.34V48.42q5.66,0,8.37-3.28t2.74-9.33v-11A26.67,26.67,0,0,1,241,9.31Q245.39,2.93,255.8,0l2.12,6.25a13.4,13.4,0,0,0-8.34,6.7,25.71,25.71,0,0,0-2.49,11.88v11a20.94,20.94,0,0,1-2.25,9.89,15.59,15.59,0,0,1-6.76,6.66,16,16,0,0,1,6.76,6.77,20.78,20.78,0,0,1,2.25,9.79V79.86a25.3,25.3,0,0,0,2.49,11.81,13.71,13.71,0,0,0,8.34,6.71Z"/><path class="cls-2" d="M430.26,104.67l-2.14-6.31a13.72,13.72,0,0,0,8.26-6.7,25.07,25.07,0,0,0,2.52-11.81V68.91a20.07,20.07,0,0,1,2.4-10,15.7,15.7,0,0,1,7.43-6.57,15.15,15.15,0,0,1-7.43-6.46,20.25,20.25,0,0,1-2.4-10.09v-11a25.44,25.44,0,0,0-2.52-11.87,13.45,13.45,0,0,0-8.26-6.7L430.26,0Q440.61,2.92,445,9.3a26.66,26.66,0,0,1,4.4,15.51v11q0,6,2.72,9.33c1.83,2.18,4.64,3.28,8.44,3.28v7.84q-5.7,0-8.44,3.35t-2.72,9.31V79.85A26.7,26.7,0,0,1,445,95.33Q440.62,101.73,430.26,104.67Z"/><path class="cls-1" d="M11.28,40.9V82.57c0,3.36-.65,5.9-2,7.61S6,92.74,3.19,92.74c-.52,0-1,0-1.56,0L0,92.6V88.8l.94,0h.92c2,0,3.29-.4,3.89-1.31a7,7,0,0,0,.91-3.9V40.9Zm13.43,0V65.57A11.82,11.82,0,0,0,27,73.13C28.43,75,31,75.94,34.77,75.94a9.73,9.73,0,0,0,8.38-4.25A17.84,17.84,0,0,0,46.2,61.05V40.9h4.6V78.74H46.55v-6.8h-.14a13.73,13.73,0,0,1-5.26,5.82,14.77,14.77,0,0,1-7.81,2.09q-6.81,0-10-3.61T20.09,65.77V40.9Zm52.75-1.08q7.94,0,12.46,5.56t4.54,14.45q0,8.85-4.55,14.44T77.49,79.85a15.38,15.38,0,0,1-8.16-2.22,11.57,11.57,0,0,1-5-6.09h-.15v21.2H59.55V40.9h4.26v7.18H64A12.58,12.58,0,0,1,69.24,42,15.8,15.8,0,0,1,77.46,39.82Zm-13.3,20q0,7.19,3.45,11.67t9.85,4.47a10.53,10.53,0,0,0,9.07-4.59,19.27,19.27,0,0,0,3.3-11.52,19.26,19.26,0,0,0-3.3-11.53,10.63,10.63,0,0,0-9.18-4.61q-6.41,0-9.8,4.05T64.16,59.8ZM102.3,40.9l12.46,32.21L126.44,40.9h4.61L114.76,84.15a19.6,19.6,0,0,1-3.57,6.5c-1.3,1.39-3.42,2.09-6.38,2.09l-1.64-.08a6.87,6.87,0,0,1-2-.28V88.47h.06a5.64,5.64,0,0,0,1.28.25,12.83,12.83,0,0,0,1.8.14,5.4,5.4,0,0,0,4.36-1.75c1-1.16,2.27-4,3.84-8.51L97.39,40.9Zm40.64-11.36V40.9h7.69v3.9h-7.69V70.61c0,1.93.36,3.2,1.08,3.8a4.28,4.28,0,0,0,2.81.89c.48,0,1,0,1.71,0s1.35-.1,2.09-.18V79c-.67,0-1.34.09-2,.11s-1.36,0-2.06,0q-4.62,0-6.44-1.75c-1.19-1.17-1.79-3.26-1.79-6.3V44.8h-6.63V40.9h6.63V29.54Zm28.49,10.28a14.74,14.74,0,0,1,12.17,5.59q4.49,5.58,4.49,14.89v.75H159a16.8,16.8,0,0,0,3.53,10.75,11,11,0,0,0,8.92,4.14A11.79,11.79,0,0,0,179,73.57a13.62,13.62,0,0,0,4.3-7.28H188q-1.62,6.83-5.66,10.2t-10.86,3.36q-8,0-12.55-5.36t-4.53-14.66q0-8.8,4.55-14.4T171.43,39.82Zm12,17.37a15,15,0,0,0-3.53-9.56,11.22,11.22,0,0,0-16.83-.28A17.33,17.33,0,0,0,159,57.19Zm28.4-16.79H213V45h-.54a12.91,12.91,0,0,0-9.84,3.92,13.65,13.65,0,0,0-3.7,9.76v20h-4.61V40.9h4.26v8.87h.14a14.74,14.74,0,0,1,5.21-6.91A13.46,13.46,0,0,1,211.86,40.4Z"/></svg>

book/installation-and-setup/choose_platforms.md

@@ -0,0 +1,29 @@
+# GitHub vs GitLab
+
+```{admonition} User types
+:class: tip
+This page is useful for user type 3-5.
+```
+
+Now that you can start, there's a first choice to be made, where to host your book:
+
+- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `<organization/username>.github.io/<book>` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/<book>`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/<book>`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in the editing-phase.
+- On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md). On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
+- On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers.
+- Because we’re in control on the server connected to GitLab, we can set up SSO login for visitors of the website. This is not an option for GitHub because we don’t own the server.
+- Both GitLab and GitHub allow for extensive options for visibility of the source code. If you're using GitHub pages, you need a free organization linked to a free eduational account. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft.
+- GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality.
+- [Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place.
+
+If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage.
+
+Here's a table summarizing the information:
+|  | GitHub   | GitLab      |
+|--|----------|-------------|
+| Website to view book online     | GitHub pages (`<organization/username>.github.io/<book>`) or custom URL 🌐         | TeachBooks (`teachbooks.tudelft.nl/<book>`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/<book>`) 🎓 |
+| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️         | Access required by TeachBooks or TU Delft OIT  🚧    |
+| Updating book website | Automated and flexible (multiple version of the book, building error insights, fast, custom urls)  🚀   | Automated but simplistic (one or two versions, command-line interface) 🛵    |
+| Student book access with SSO    | Not available for GitHub pages ❌, optional with custom URL  ✅ | Optional  ✅          |
+| Teacher/TA access to Git repository   | Private (if part of organization linked to educational account) /public  👀   | Private / public / internally TU Delft, editing requires requires SSO login  👥   |
+| GitHub Desktop | Well integrated 😎 | Basic integration 🙂 |
+| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️|

book/installation-and-setup/extension.md

@@ -1,22 +0,0 @@
-# Making comments on the website
-
-This section will explain how to use the extension hypothesis in order to make comments, an alternative is Utterances but this is only available for GitHub-hosted books.
-
-Firstly, you will need to open your interactive text book in your browser. Take as example the [MUDE](https://mude.citg.tudelft.nl/book/intro.html) book.
-
-If you look at the top right of the page, you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension. The extension we are currently using is called Hypothesis. In order to use it you will have to make an account. Through the extension you will be able to highlight relevant sections and write notes and annotations. Comments on the content of the book can be submitted by making annotations and posting them to group called Feedback!
-
-## Set up hypothesis in your book
-Add this to `_config.yml`. Need to create an account.
-
-```
-html:
-  comments:
-    hypothesis: true
-```
-
-```{admonition} Tips
-:class: tip
-
-- use {ref}`remove_from_publish` to enable in Draft book only
-```

book/installation-and-setup/jupyter-book-setup.md

@@ -5,11 +5,11 @@
 This page is useful for user type 5.
 ```
 
-Jupyter Book is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository.
+<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> is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository.
 
 ## Build a book
 
-As soon as you've installed your book environment with jupyter-book you can build your book locally. The official [jupyter-book](https://jupyterbook.org/en/stable/basics/build.html) documentation is quite extensive. Only two notes: first navigate to the directory where your book is to leave out the `path-to-book` and use `--all` whenever building a book to make sure the table of contents fully updates:
+As soon as you've installed your book environment with jupyter-book you can build your book locally. The official <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> documentation is quite extensive. Only two notes: first navigate to the directory where your book is to leave out the `path-to-book` and use `--all` whenever building a book to make sure the table of contents fully updates:
 
 ```
 jupyter-book build <path-to-book> --all

book/installation-and-setup/user_types.md

@@ -23,7 +23,7 @@ Different types of users will interact with the website or the Jupyter Books dif
 4. **Colleague making text adjustments to multiple files at the same time locally**. <br>
     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 4 has more knowledge to make changes to python files the book as well. This user can build the book online.
 
-5. **Colleague making text and python adjustments to multiple files at the same time locally**. <br>
+5. **Colleague making text and code (especially Python) adjustments to multiple files at the same time locally**. <br>
 <img src="figures/type 5.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
 
    This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally.

book/intro.md

@@ -1,6 +1,6 @@
 # TeachBooks Manual
 
-This is an introduction to Git, VS Code and Jupyter Books for teachers and teaching assistants involved in TeachBooks. 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/).
+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, please contact Tom van Woudenberg, Robert Lanzafame or one of our TAs Caspar Jungbacker or Julie Kirsch at TeachBooks@tudelft.nl.
+If you encounter any issues, please contact Tom van Woudenberg, Robert Lanzafame or one of our TAs Julie Kirsch at TeachBooks@tudelft.nl.

book/workflows/githubtemplate.md

@@ -1,58 +0,0 @@
-# Your first TeachBook using the template
-
-```{admonition} User types
-:class: tip
-This page is useful for user type 3, 4 and 5.
-```
-
-This page shows you how as an example how to start your own Jupyter Book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book.
-
-`````{tab-set}
-````{tab-item} GitHub template
-
-1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template:
-
-```{figure} figures/use_template.png
-: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
-:name: create_new_repository
-```
-
-3. Set source for GitHub pages to under <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right">    <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` - <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-browser">
-    <path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25ZM14.5 6h-13v7.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25Zm-6-3.5v2h6V2.75a.25.25 0 0 0-.25-.25ZM5 2.5v2h2v-2Zm-3.25 0a.25.25 0 0 0-.25.25V4.5h2v-2Z"></path>
-</svg> `Pages` - `Build and deployment` - `Source` - `GitHub Actions`:
-
-```{figure} figures/set_up_pages.png
-:name: activate_pages
-```
-
-4. Set repository website as your GitHub Pages website under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-code UnderlineNav-octicon d-none d-sm-inline">
-    <path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path>
-</svg>`Code`- `About` - <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right">    <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg> - `Website` - `Use your GitHub Pages Website`
-
-```{figure} figures/use_github_pages_website.png
-:name: github_pages_as_website
-```
-
-4. Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline">    <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions` - `All workflows`:
-
-```{figure} figures/action.png
-:name: action
-```
-5. When the workflow has finished, visit your build book at `https://<username>.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.
-
-To learn more about how we do this, please see the [GitHub Actions documentation](https://docs.github.com/en/actions) and our deployment pipeline configuration file `.github/workflows/deploy-book-ghpages.yml` [here](https://github.com/TeachBooks/template/blob/main/.github/workflows/deploy-book-ghpages.yml).
-
-````
-
-````{tab-item} GitLab template
-```{error} To be written
-```
-````
-`````
-
-Now that you have your book, you can continue editing your book as described in the other chapters in this book

book/workflows/publish.md

@@ -1,3 +1,4 @@
+(publish_students)=
 # Publish to students
 
 For this step it is assumed you’re using TeachBook’s GitHub actions or TeachBook’s GitLab pipeline.

requirements.txt

@@ -1,6 +1,5 @@
 jupyter-book
 sphinx-inline-tabs
-jupyterlite-xeus-python
 jupyterlite-sphinx
 
 --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple