admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-13 06:45:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'CollaborationGit' of gitlab.tudelft.nl:interactivetextbooks-citg/jupyter-book-manual into CollaborationGit

Browse source
This commit is contained in:
Julie Kirsch 2024-04-20 16:20:38 +02:00
commit 51f45d6ea3
45 changed files with 28467 additions and 440 deletions
Download patch file Download diff file Expand all files Collapse all files

52
book/_static/bimodal_field.mtl Normal file
View file

@ -0,0 +1,52 @@
# Blender 4.0.2 MTL File: 'bimodal_distribution_v06_to_obj.blend'
# www.blender.org
newmtl bedrock_dark
Ns 250.000000
Ka 1.000000 1.000000 1.000000
Kd 0.800000 0.800000 0.800000
Ks 0.500000 0.500000 0.500000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2
newmtl grass_flat
Ns 250.000000
Ka 1.000000 1.000000 1.000000
Kd 0.261166 0.800000 0.226093
Ks 0.500000 0.500000 0.500000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2
newmtl gravel
Ns 250.000000
Ka 1.000000 1.000000 1.000000
Kd 0.155926 0.127438 0.088656
Ks 0.500000 0.500000 0.500000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2
newmtl soil
Ns 250.000000
Ka 1.000000 1.000000 1.000000
Kd 0.372228 0.272421 0.169322
Ks 0.500000 0.500000 0.500000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2
newmtl water
Ns 250.000000
Ka 1.000000 1.000000 1.000000
Kd 0.026867 0.549270 0.800000
Ks 1.000000 1.000000 1.000000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 0.500000
illum 2

27187
book/_static/bimodal_field.obj Normal file
View file

File diff suppressed because it is too large Load diff

155
book/_static/element_render_box.html Normal file
View file

@ -0,0 +1,155 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Subsurface</title>
<style>
html, body {
margin: 0;
height: 100%;
}
#c {
width: 100%;
height: 100%;
display: block;
}
</style>
</head>
<body>
<canvas id="c"></canvas>
<script type="module">
// Path to object
var path_obj = "bimodal_field.obj";
var path_mtl = "bimodal_field.mtl";
// Three.js - Load .OBJ and .MTL file - Windmill2
// from https://threejsfundamentals.org/threejs/threejs-load-obj-materials-windmill2.html
import * as THREE from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/build/three.module.js';
import { OrbitControls } from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/examples/jsm/controls/OrbitControls.js';
import { OBJLoader } from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/examples/jsm/loaders/OBJLoader.js';
import { MTLLoader } from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/examples/jsm/loaders/MTLLoader.js';
function main() {
const canvas = document.querySelector('#c');
const renderer = new THREE.WebGLRenderer({ canvas });
const fov = 45;
const aspect = 2; // the canvas default
const near = 0.1;
const far = 100;
const camera = new THREE.PerspectiveCamera(fov, aspect, near, far);
camera.position.set(0, 10, 20);
const controls = new OrbitControls(camera, canvas);
controls.target.set(0, 5, 0);
controls.update();
const scene = new THREE.Scene();
scene.background = new THREE.Color('white');
{
const skyColor = 0xB1E1FF; // light blue
const groundColor = 0xB97A20; // brownish orange
const intensity = 1;
const light = new THREE.HemisphereLight(skyColor, groundColor, intensity);
scene.add(light);
}
{
const color = 0xFFFFFF;
const intensity = 1;
const light = new THREE.DirectionalLight(color, intensity);
light.position.set(5, 10, 2);
scene.add(light);
scene.add(light.target);
}
function frameArea(sizeToFitOnScreen, boxSize, boxCenter, camera) {
const halfSizeToFitOnScreen = sizeToFitOnScreen * 0.5;
const halfFovY = THREE.MathUtils.degToRad(camera.fov * .5);
const distance = halfSizeToFitOnScreen / Math.tan(halfFovY);
// compute a unit vector that points in the direction the camera is now
// in the xz plane from the center of the box
const direction = (new THREE.Vector3())
.subVectors(camera.position, boxCenter)
.multiply(new THREE.Vector3(1, 0, 1))
.normalize();
// move the camera to a position distance units way from the center
// in whatever direction the camera was from the center already
camera.position.copy(direction.multiplyScalar(distance).add(boxCenter));
// pick some near and far values for the frustum that
// will contain the box.
camera.near = boxSize / 100;
camera.far = boxSize * 100;
camera.updateProjectionMatrix();
// point the camera to look at the center of the box
camera.lookAt(boxCenter.x, boxCenter.y, boxCenter.z);
}
{
const mtlLoader = new MTLLoader();
mtlLoader.load(path_mtl, (mtl) => {
mtl.preload();
const objLoader = new OBJLoader();
objLoader.setMaterials(mtl);
objLoader.load(path_obj, (root) => {
scene.add(root);
// compute the box that contains all the stuff
// from root and below
const box = new THREE.Box3().setFromObject(root);
const boxSize = box.getSize(new THREE.Vector3()).length();
const boxCenter = box.getCenter(new THREE.Vector3());
// set the camera to frame the box
frameArea(boxSize * 1.2, boxSize, boxCenter, camera);
// update the Trackball controls to handle the new size
controls.maxDistance = boxSize * 10;
controls.target.copy(boxCenter);
controls.update();
});
});
}
function resizeRendererToDisplaySize(renderer) {
const canvas = renderer.domElement;
const width = canvas.clientWidth;
const height = canvas.clientHeight;
const needResize = canvas.width !== width || canvas.height !== height;
if (needResize) {
renderer.setSize(width, height, false);
}
return needResize;
}
function render() {
if (resizeRendererToDisplaySize(renderer)) {
const canvas = renderer.domElement;
camera.aspect = canvas.clientWidth / canvas.clientHeight;
camera.updateProjectionMatrix();
}
renderer.render(scene, camera);
requestAnimationFrame(render);
}
requestAnimationFrame(render);
}
main();
</script>
</body>
</html>

35
book/_toc.yml
View file

@ -4,44 +4,43 @@ root: intro
parts:
- caption: Getting started!
chapters:
- file: installation-and-setup/user_types
- file: installation-and-setup/git
- file: installation-and-setup/overview
sections:
- file: installation-and-setup/extension
- file: installation-and-setup/git-setup
- file: installation-and-setup/vscode-setup
- file: installation-and-setup/git-setup_local
- file: installation-and-setup/anaconda
- file: installation-and-setup/add_conda_to_path
- file: installation-and-setup/working-directory
- file: installation-and-setup/environments
- file: installation-and-setup/git_bash_conda_vs-code.md
- file: installation-and-setup/jupyter-book-setup
- file: workflows/overview
sections:
- file: workflows/collaboration
sections:
- file: workflows/milestones_issues
- file: workflows/repositories
- file: workflows/permissions
- file: workflows/branches
- file: workflows/edit_book
- file: workflows/publish
- file: workflows/githubtemplate
- file: workflows/githubtemplate
- file: workflows/collaboration
sections:
- file: workflows/milestones_issues
- file: workflows/branches
- file: workflows/edit_book
- file: workflows/check_changes_online
- file: workflows/merge_request
- file: workflows/publish
- caption: Features
chapters:
- file: basic-features/overview
sections:
- file: basic-features/recipes.md
- file: installation-and-setup/extension
- file: features/overview
sections:
- file: features/remove_from_publish
- file: features/custom_toc.md
- file: features/custom_download.md
- file: features/hypothesis
- file: features/interactive_element.ipynb
sections:
- file: features/grasple.md
- file: features/h5p.md
- file: features/adding_basic_HTML_elements.md
- file: features/HTML_javascript.md
sections:
- file: features/adding_HTML_elements.md
- file: features/creating_basic_HTML_elements.md
- file: features/python_interactivity.md
sections:
- file: features/live_code.md

5
book/basic-features/overview.md
View file

@ -1,5 +1,10 @@
# Basic Jupyter Book Features
```{admonition} User types
:class: tip
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.

11
book/features/HTML_javascript.md Normal file
View file

@ -0,0 +1,11 @@
# Interactive HTML/JavaScript elements
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:
<iframe src="../_static/element_render_box.html" width="600" height="400" frameborder="0"></iframe>
Or other interactive graphs:
<iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>

197
book/features/adding_HTML_elements.md Normal file
View file

@ -0,0 +1,197 @@
# Adding interactive HTML/JavaScript elements
In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
<iframe src="../_static/element_render_box.html" width="600" height="400" frameborder="0"></iframe>
## Storing the HTML file
TeachBooks like this one are built from a Git project, comprising of different files and folders that are assembled into a webpage. It is generally not possible to paste the code of your HTML element directly into one of the project's Markdown files. Instead, you will have to store the files separately somewhere in the folder structure, then embed them later on. For this project, the book's root folder contains a ´_static´ folder which we can use to store our HTML/JS file. Some elemenets - such as the one above - may require additional files. The HTML element above, for instance, specifies a renderer using [THREE.js](https://threejs.org/) that displays a digital model. This model is specified as an .obj file (which defines its geometry) and a .mtl file (which defines its materials - its colors, reflectivity, transparency, and so on). We can store these files in the same ´_static´ folder.
## Embedding HTML files via iframes
If we want to embed our HTML/JS element in a Markdown page, we must use an inline frame, also known as an iframe. In code, an iframe looks like this:
```html
<iframe src="../_static/element_render box.html" width="600" height="300" frameborder="0"></iframe>
```
What does this code do? In HTML, certain active parts of the code are defined as tags surrounded by `<` and `>` symbols. The tag `<iframe>` opens the iframe environment, the `<iframe/>` tag closes it again. Inside the opening tag, we can further specify properties of the iframe. These properties are usually defined as strings, that is to say, surrounded by quotation marks. Some of the more common iframe properties are:
- `src`: This specifies the **source** of the iframe, the HTML file it will display.
- `width`: This specifies the **width** of the iframe in pixels.
- `height`: This specifies the **height** of the iframe in pixels.
- `frameborder`: This flag specifies whether a border should be drawn around the iframe (`"1"`) or not (`"0"`).
- `scrolling`: Specifies whether or not to display scrollbars for the iframe, in case the embedded content is larger than the iframe. Possible values are `"yes"`, `"no"`, and `"auto"`. I recommend either creating HTML elements of the same size, or adjusting their size dynamically to their contained - in this case, the iframe.
- `allowfullscreen`: Specifies whether or not to allow the iframe to be displayed in fullscreen mode.
- `loading`: Specifies how the browser should handle the loading of the iframe content. Possible values are eager (load immediately) and lazy (load on demand).
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 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`.
## Viewing result at local build
To view the final result locally, it's required to setup a [local python webserver](setup-local-server).
## HTML code for the 3D render element
To conclude, I provide the HTML/JavaScript code for the 3D render element above. To understand what the code below does in more detail, please refer to the [next article](creating_basic_HTML_elements.md). One thing I want to direct your attention to are the paths specified in the first few lines of the `<script>` environment. Here, we do not have to navigate to a different local folder because we initially stored our `.obj` and `.mtl` files in the same folder as the `element_render_box.html` file. If they would be stored in a different folder, we have to specify either an absolute path (e.g., via a URL) or a relative path, as explained above.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Subsurface</title>
<style>
html, body {
margin: 0;
height: 100%;
}
#c {
width: 100%;
height: 100%;
display: block;
}
</style>
</head>
<body>
<canvas id="c"></canvas>
<script type="module">
// Path to object
var path_obj = "bimodal_field.obj";
var path_mtl = "bimodal_field.mtl";
// Three.js - Load .OBJ and .MTL file - Windmill2
// from https://threejsfundamentals.org/threejs/threejs-load-obj-materials-windmill2.html
import * as THREE from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/build/three.module.js';
import { OrbitControls } from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/examples/jsm/controls/OrbitControls.js';
import { OBJLoader } from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/examples/jsm/loaders/OBJLoader.js';
import { MTLLoader } from 'https://threejsfundamentals.org/threejs/resources/threejs/r127/examples/jsm/loaders/MTLLoader.js';
function main() {
const canvas = document.querySelector('#c');
const renderer = new THREE.WebGLRenderer({ canvas });
const fov = 45;
const aspect = 2; // the canvas default
const near = 0.1;
const far = 100;
const camera = new THREE.PerspectiveCamera(fov, aspect, near, far);
camera.position.set(0, 10, 20);
const controls = new OrbitControls(camera, canvas);
controls.target.set(0, 5, 0);
controls.update();
const scene = new THREE.Scene();
scene.background = new THREE.Color('white');
{
const skyColor = 0xB1E1FF; // light blue
const groundColor = 0xB97A20; // brownish orange
const intensity = 1;
const light = new THREE.HemisphereLight(skyColor, groundColor, intensity);
scene.add(light);
}
{
const color = 0xFFFFFF;
const intensity = 1;
const light = new THREE.DirectionalLight(color, intensity);
light.position.set(5, 10, 2);
scene.add(light);
scene.add(light.target);
}
function frameArea(sizeToFitOnScreen, boxSize, boxCenter, camera) {
const halfSizeToFitOnScreen = sizeToFitOnScreen * 0.5;
const halfFovY = THREE.MathUtils.degToRad(camera.fov * .5);
const distance = halfSizeToFitOnScreen / Math.tan(halfFovY);
// compute a unit vector that points in the direction the camera is now
// in the xz plane from the center of the box
const direction = (new THREE.Vector3())
.subVectors(camera.position, boxCenter)
.multiply(new THREE.Vector3(1, 0, 1))
.normalize();
// move the camera to a position distance units way from the center
// in whatever direction the camera was from the center already
camera.position.copy(direction.multiplyScalar(distance).add(boxCenter));
// pick some near and far values for the frustum that
// will contain the box.
camera.near = boxSize / 100;
camera.far = boxSize * 100;
camera.updateProjectionMatrix();
// point the camera to look at the center of the box
camera.lookAt(boxCenter.x, boxCenter.y, boxCenter.z);
}
{
const mtlLoader = new MTLLoader();
mtlLoader.load(path_mtl, (mtl) => {
mtl.preload();
const objLoader = new OBJLoader();
objLoader.setMaterials(mtl);
objLoader.load(path_obj, (root) => {
scene.add(root);
// compute the box that contains all the stuff
// from root and below
const box = new THREE.Box3().setFromObject(root);
const boxSize = box.getSize(new THREE.Vector3()).length();
const boxCenter = box.getCenter(new THREE.Vector3());
// set the camera to frame the box
frameArea(boxSize * 1.2, boxSize, boxCenter, camera);
// update the Trackball controls to handle the new size
controls.maxDistance = boxSize * 10;
controls.target.copy(boxCenter);
controls.update();
});
});
}
function resizeRendererToDisplaySize(renderer) {
const canvas = renderer.domElement;
const width = canvas.clientWidth;
const height = canvas.clientHeight;
const needResize = canvas.width !== width || canvas.height !== height;
if (needResize) {
renderer.setSize(width, height, false);
}
return needResize;
}
function render() {
if (resizeRendererToDisplaySize(renderer)) {
const canvas = renderer.domElement;
camera.aspect = canvas.clientWidth / canvas.clientHeight;
camera.updateProjectionMatrix();
}
renderer.render(scene, camera);
requestAnimationFrame(render);
}
requestAnimationFrame(render);
}
main();
</script>
</body>
</html>
```

2
book/features/adding_basic_HTML_elements.md → book/features/creating_basic_HTML_elements.md
View file

@ -1,4 +1,4 @@
# Adding basic interactive HTML/JavaScript elements
# 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):

5
book/features/custom_download.md
View file

@ -1,5 +1,10 @@
# Page download options
```{admonition} User types
:class: tip
This section is useful for user type 4-6.
```
You can control the download option of the book in two ways:
- Disabling downloading using cell tags `disable-download-page`
- Add / replace download link with custom link using `spinhx-download-link-replacer`

5
book/features/custom_toc.md
View file

@ -1,5 +1,10 @@
# Exclude parts of book from published book
```{admonition} User types
:class: tip
This section is useful for user type 3-6.
```
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:
```

19
book/features/hypothesis.md
View file

@ -1,19 +0,0 @@
# Hypothesis
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
- figure out how to use this...
```

18
book/features/interactive_element.ipynb
View file

@ -15,9 +15,8 @@
" - JupyterQuiz: code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file.\n",
" - H5p: TU-Delft-licensed tool to create questions (and many other interactive elements) using an [online GUI](https://tudelft.h5p.com/). These elements are embedded into the book using an iframe which requires very little coding. This elements are easier to implement than the JupyterQuiz and have more features (although proper numerical answer questions are missing). More information on this is provided in [this subchapter](h5p.md)\n",
" - Grasple-exercises: TU-Delft-licensed tool to creating math-based quiz questions. Again, these elements are embedded into the book using an iframe which requiries very little coding. These elements are very well suited to math-based problems as it allows analytical evaluation of numerical values and formulas. Furthermore, Grasple allows parameterization (not required for formative exercises). More information on this is provided in [this subchapter](grasple.md)\n",
" - Non-kernel-based widgets: You can create interactive widgets with Python which doesn't need a kernel to run online:\n",
" - You can create html/javascript widgets, an example is shown in [this subchapter](adding_basic_HTML_elements.md)\n",
" - The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows this use.\n",
" - Custom HTML/Javascript widgets: You can create and embed html/javascript widgets, an example is shown in [this subchapter](HTML_javascript.md)\n",
" - HTML/Javascript widgets using Plotly. The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript.\n",
"\n",
"Examples of each type is shown below based on the following problem:\n",
"\n",
@ -310,7 +309,18 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Interactive widget without kernel\n",
"## HTML/Javascript\n",
"\n",
"The example below shows a custom HTML/Javascript element\n",
"\n",
"<iframe src=\"../_static/element_pdf_and_cdf.html\" width=\"600\" height=\"300\" frameborder=\"0\"></iframe>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Plotly graph\n",
"\n",
"The example below is taken from the FEM-module by Frans van der Meer.\n",
"When using Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Alternatively, add the following lines of code to your notebook to have a valid output in the book as well:\n",

2
book/features/jupyterlite/jupyterlite.md
View file

@ -1,4 +1,4 @@
# JupyterLite-Sphinx: Interactive elements
# JupyterLite-Sphinx
By popular demand: how to include interactive pieces of code in your Jupyter Book. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a Jupyter Book with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.

13
book/features/live_code.ipynb
View file

@ -4,7 +4,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Python-enabled interactivity\n",
"# Sphinx-thebe\n",
"\n",
"Our book has been enable to run Python code live in the browser (thanks Max!). This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n",
"\n",
@ -74,11 +74,7 @@
"\n",
"## Instructions: local build\n",
"\n",
"To test the fuctionality, you have to run a local server, otherwise the interactivity doens't work. So, you cannot just open the `index.html` file any more. This can be done with the following steps:\n",
"1. build the book by running ` jupyter book build <directory of your book>`. If you are using Windows you should use the Git Bash terminal. Set this as your default in VS Code, then open it using \"New Terminal.\" If you have not already done so, you will need to allow Git Bash to use your Python libraries by running the command `conda init bash`.\n",
"2. Set up a server by running `python -m http.server 8000`.\n",
"3. Open the book by going to [http://localhost:8000/](http://localhost:8000/) in your browser. You may need to reload the page once the rebuild is complete. You can do this on Chrome by right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. Or try `ctrl`+`F5`\n",
"4. Go to any page that is created from a Jupyter notebook\n",
"To test the fuctionality, you have to run a local server, otherwise the interactivity doens't work. So, you cannot just open the `index.html` file any more. This can be done with the steps shown in {ref}`setup-local-server`.\n",
"\n",
"If you push to main, you can test the interactivity on the book-draft website as well.\n",
"\n",
@ -115,11 +111,6 @@
"%pip install package_name\n",
"```\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": []
}
],
"metadata": {

7
book/features/python_interactivity.md
View file

@ -1,5 +1,10 @@
# Python-enabled interactivity
```{admonition} User types
:class: tip
This section is useful for user type 5-6.
```
In general, there are two option to include python-enabled interactivity embedded in your book:
- Using our [own sphinx-thebe extension](live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!
- Using our [own sphinx-thebe extension](./live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!
- Using [JupyterLite](jupyterlite/jupyterlite.md) to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension.

BIN
book/images/image.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 55 KiB

138
book/installation-and-setup/anaconda.md
View file

@ -1,6 +1,15 @@
# Anaconda
# Managing code-related software: Anaconda
Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. You can download the installation files [here](https://www.anaconda.com/download).
```{admonition} User types
:class: tip
This page is useful for user type 5.
```
Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. Unfortunately, each of these packages are themselves require a number of different packages to function properly. Do you like installing all of them? You shouldn't---but where do you get them come from? Many of those packages are packages required by only a few specific packages. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run install a specific package, `conda` (part of Anaconda) checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` (collection of software with a specific version) that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you use them to install a package. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly!
## Installing anaconda
You can download the installation files [here](https://www.anaconda.com/download).
When installing Anaconda, keep in mind the following:
@ -17,4 +26,127 @@ Once installed, we will check to make sure you are ready to use Python. Anaconda
3. You should be running at least Python 3.11. If not, don’t worry, we will try to fix it below (but first make sure you have updated Anaconda as described above)
4. Which environment are you in? The name is between parenthesis at the bottom of your Anaconda Prompt: by default, this should be `(base)`.
5. How many other environments do you have? Execute `conda env list` to see a complete list.
6. Do you see the `*` in the list of environments? That is indicating your current active environment. Unless you have changed something, it should be `base`. And if you just installed Anaconda for the first time, this will be your only environment!
6. Do you see the `*` in the list of environments? That is indicating your current active environment. Unless you have changed something, it should be `base`. And if you just installed Anaconda for the first time, this will be your only environment!
## Software version control: environments
A python virtual environment is, like the name might suggest, a reserved space within the computer that contains downloaded python packages. Each environment is like a clean slate and the packages and dependencies of one environment have no influence on other environments. In that sense, it makes sense to create a new (working) environment every time you start a new project. You'll redo the next steps on this page therefor many times in the future!
### Set-up environments
Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book.
For simplicity we will call this environment `my_new_book`, but you can give it any name you like.
1. Open the commmand line interface (see above) or continue in the same session if it is still active
2. Execute: `conda create --name my_new_book pip` (this may take several minutes)
3. Activate: `conda activate my_new_book`
<br> Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book)`
4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section)
Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `jupyter-book`. More information about this package [here](jupyter-book-setup.md).
### Import environments
Working on larger projects (with many cool interactive features) may require you to install a lot of python packages. It can be useful to specify the required packages in a text-based file (for example `environment.yml`) and then telling `conda` to create the environment based on the contents of the file!
Moreover, if you are joining a team that is working on complex projects, it can be useful for you to create a new environment based on use such a text-based file in order to create an up-to-date environment that will give you a flying start. The team might also provide a `requirements.txt` file which specifies all the packages you need to download in order to work on the project. Now it should also become clear why its preferable to create new environment for each project/book that you work on because they might require you to use different packages!
Here's an example of what a `requirements.txt` file might look like.
```
# first list the packages you wish to download from PyPI
sympy
# now list the packages (and the respective url) you wish to download from the GitLab package registry
--index-url https://__token__:glpat-JduurUdhDczFJzvzZN4G@gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple
teachbooks
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple
jupyterbook_patches ~= 0.1.4
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
sphinx-thebe ~= 0.9.9
# lastly any packages you wish to download directly from a Git repository
download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer
```
This file needs to be manually updated by the team everytime a new package is required. It will be useful to routinely update the packages in your environment by downloading the required packages again. The packages used by sphinx-thebe or JupyterLite-Sphinx are not influenced by `requirements.txt`.
You can do this by navigating your command line interface to the folder with `requirements.txt`:
````{tab} Windows
1. Open the folder you wish to use as your working directory in the File Explorer
2. Right-click the folder and click `Git bash here`
3. Confirm you are in the right place by inspecting the path listed in your prompt (it should typically start with be `C:\ ...` and end wit `>`)
4. You can also inspect the contents of the directory by executing `dir`
````
````{tab} Mac
1. Find the folder you wish to use as your working directory
2. Right-click and select Get Info
3. Hold down the Alt (Option) key; the menu items will change\
4. Select Copy … As Pathname
5. You can now paste this path into the Terminal after the `cd` command
6. Confirm you are in the right place by executing the command `pwd`
7. You can also inspect the contents of the directory by executing ls (that’s a lower case “L”)
````
Now you can install the required packages with: `pip install -r requirements.txt`. The TeachBooks team works with these `requirements.txt` files which makes this an essential step in the set-up of your environment!
### Export environment
If you want to create a file listing the required packages yourself, you can do it by creating a file with the following file extension: the `*.yml` file (pronounced "yah-mul"). It is a text-readable file, that stands for "Yet another Markup Language." This is one of _many_ types of files that use a particular type of text formatting to give a computer specific instructions. It is very similar to the way Markdown formatting works.
The `environment.yml` file will look something like this:
```
name: MUDE
dependencies:
- python=3.11
- numpy
- scipy
- matplotlib
- statsmodels
- pip
- conda-forge::jupyterlab
```
You should see that it uses a colon `:` to list the information, like name and dependencies. This will be processed by `conda` when creating the new environment.
If you want to create an environment based on an existing `*.yml` file, you can follow these steps:
1. You need to have the file locally on your computer (for example by cloning the git repositery that it is in)
2. Open Anaconda Prompt
3. Navigate to your working directory (where this file and `environment.yml` is located)
4. Finally, execute this command: `conda env create -f environment.yml`
This may take several minutes because you are installing many packages at once! Keep an eye on the terminal window as this process is completed. First `conda` is collecting information about the dependencies, then it will _solve_ the environment; in other words, figure out which version of each package it should use. Once it is ready, it will present the list of packages and proceed with the "installation" (really just downloading `*.py` files and putting them in a folder on your computer)
Note that the prompt may ask you to confirm that the installation should proceed, depending on your system settings.
Once the environment is created, we can activate it, and also check that everything was installed properly. Try `conda env export -n my_new_book` to see what was installed by "default." The list is very long, even though we only asked for a few packages!
It is also interesting to try `conda env export --from-history` (make sure you activated it already), which shows the specific packages requested.
### Deleting Environments
Although the environments do not interfere with each other, you might want to delete environment you don't use. Try running the following in a Terminal or Anaconda prompt, which will list the file locations of your environment.
`conda info --envs`
If you have many projects, the amount of environments can take up a lot of space on your computer as one environment can get very large. It is a good idea to remove environments once you know they are no longer useful.
To remove an environment, in your Anaconda Prompt, run:
`conda remove --name my_new_book --all`
You will be asked to confirm the deletion, then it may take a while to remove all of the files. To verify that the environment was removed, in your terminal window or an Anaconda Prompt, run:
`conda info --envs`
The environments list that displays should not show the removed environment.
This information has been taken from the [Anaconda documentation](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#removing-an-environment).
Now you can delete any other useless environments you have lying around on your computer!

116
book/installation-and-setup/environments.md
View file

@ -1,116 +0,0 @@
# Creating python environments
A python virtual environment is, like the name might suggest, a reserved space within the computer that contains downloaded python packages. Each environment is like a clean slate and the packages and dependencies of one environment have no ifluence on other environments. In that sense, it makes sense to create a new (working) environment every time you start a new project.
## Set-up environments
Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book. Please make sure you have [upgraded Anaconda](https://docs.anaconda.com/free/anaconda/install/update-version/) (if you didn't just download it) before proceeding with these steps:
For simplicity we will call this environment `my_new_book`, but you can give it any name you like.
1. Open the commmand line interface (see above) or continue in the same session if it is still active
2. Execute: `conda create --n my_new_book pip` (this may take several minutes)
3. Activate: `conda activate my_new_book`
<br> Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book)`
4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section)
Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `jupyter-book`. More information about this package [here](jupyter-book-setup.md).
## Text-based files
Working on larger projects (with many cool interactive features) may require you to install a lot of python packages. It can be useful to specify the required packages in a text-based file (for example `environment.yml`) and then telling `conda` to create the environment based on the contents of the file!
Moreover, if you are joining a team that is working on complex projects, it can be useful for you to create a new environment based on use such a text-based file in order to create an up-to-date environment that will give you a flying start. The team might also provide a `requirements.txt` file which specifies all the packages you need to download in order to work on the project. Now it should also become clear why its preferrable to create new environment for each project/book that you work on because they might require you to use different packages!
Here's an example of what a `requirements.txt` file might look like.
```
# first list the packages you wish to download from PyPI
sympy
# now list the packages (and the respective url) you wish to download from the GitLab package registry
--index-url https://__token__:glpat-JduurUdhDczFJzvzZN4G@gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple
teachbooks
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple
jupyterbook_patches ~= 0.1.4
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
sphinx-thebe ~= 0.9.9
# lastly any packages you wish to download directly from a Git repository
download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer
```
This file needs to be manually updated by the team everytime a new package is required. It will be useful to routinely update the packages in your environment by downloading the required packages again. The packages used by sphinx-thebe or JupyterLite-Sphinx are not influenced by `requirements.txt`.
This can be done by typing the following in your terminal (in the right environment): `pip install -r requirements.txt`.
**Note that the TeachBooks team works with these `requirements.txt` files which makes this an essential step in the set-up of your environment!**
```{note}
### Dependencies
Unfortunately, each of these packages are themselves require a number of different packages to function properly. To see this, try executing the following command in your Anaconda prompt or terminal. You can also try it for `(base)`.
`conda env export -n my_new_book`
You should see a long list of packages. Do you remember installing all of them with `conda install` or `pip install`? You shouldn't---but where did they come from? Many of them are packages required by the packages that you _did_ specifically install. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run `conda install numpy`, for example, `conda` checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you run them with an `install` command. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly!
```
## Create an environment from text-based file
If you want to create a file listing the required packages yourself, you can do it by creating a file with the following file extension: the `*.yml` file (pronounced "yah-mul"). It is a text-readable file, that stands for "Yet another Markup Language." This is one of _many_ types of files that use a particular type of text formatting to give a computer specific instructions. It is very similar to the way Markdown formatting works.
The `environment.yml` file will look something like this:
```
name: MUDE
dependencies:
- python=3.11
- numpy
- scipy
- matplotlib
- statsmodels
- pip
- conda-forge::jupyterlab
```
You should see that it uses a colon `:` to list the information, like name and dependencies. This will be processed by `conda` when creating the new environment.
If you want to create an environment based on an existing `*.yml` file, you can follow these steps:
1. You need to have the file locally on your computer (for example by cloning the git repositery that it is in)
2. Open Anaconda Prompt
3. Navigate to your working directory (where this file and `environment.yml` is located)
4. Finally, execute this command: `conda env create -f environment.yml`
This may take several minutes because you are installing many packages at once! Keep an eye on the terminal window as this process is completed. First `conda` is collecting information about the dependencies, then it will _solve_ the environment; in other words, figure out which version of each package it should use. Once it is ready, it will present the list of packages and proceed with the "installation" (really just downloading `*.py` files and putting them in a folder on your computer)
Note that the prompt may ask you to confirm that the installation should proceed, depending on your system settings.
Once the environment is created, we can activate it, and also check that everything was installed properly. Try `conda env export -n my_new_book` to see what was installed by "default." The list is very long, even though we only asked for a few packages!
It is also interesting to try `conda env export --from-history` (make sure you activated it already), which shows the specific packages requested.
## Deleting Environments
Although the environments do not interfere with each other, you might want to delete environment you don't use. Try running the following in a Terminal or Anaconda prompt, which will list the file locations of your environment.
`conda info --envs`
If you have many projects, the amount of environments can take up a lot of space on your computer as one environment can get very large. It is a good idea to remove environments once you know they are no longer useful.
To remove an environment, in your Anaconda Prompt, run:
`conda remove --name my_new_book --all`
You will be asked to confirm the deletion, then it may take a while to remove all of the files. To verify that the environment was removed, in your terminal window or an Anaconda Prompt, run:
`conda info --envs`
The environments list that displays should not show the removed environment.
This information has been taken from the [Anaconda documentation](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#removing-an-environment).
Now you can delete any other useless environments you have lying around on your computer!

17
book/installation-and-setup/extension.md
View file

@ -1,7 +1,22 @@
# Making comments on the website
This section will explain how to use the extension in order to make comments.
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
```

19
book/installation-and-setup/git-setup.md
View file

@ -1,19 +0,0 @@
# What is Git and GitLab?
In this section you will learn how to perform basic Git actions in the online interface of GitLab.
## What is Git?
Git is a version control system (VCS), used by a wide variety of engineers and software developers to work on projects in parallel together. It provides multiple benefits such as tracking changes to files, working side by side with other people, and the ability to rollback to previous versions of files without losing track of newer changes. It is a free and open sources software.
## What is GitLab?
GitLab is a cloud-based version control system built around git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com.
## Terminology
This is a (non-exhaustive) list of terminology that will be used in GitLab.
- Repository: a collection of files and folders, along with a history of their changes and who made them.
- Commit: a snapshot of the current state of the repository.
- Branch: a development line.
- Pushing: uploading new commits to the remote repository.

92
book/installation-and-setup/git-setup_local.md
View file

@ -1,48 +1,33 @@
# How do I use Git locally?
# Git: GitHub Desktop / Git in VS Code
In this section you will learn how to perform basic Git actions in VS Code / GitHub Desktop. Courses on Git usually make use of the command line interface to do these actions, but this introduces a steep learning curve. Instead, using Git from VS Code / GitHub Desktop is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line.
```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```
## GitHub Desktop
GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: GitHub Desktop!
While GitLab is a cloud-based version control system built around git, GitHub Desktop makes it possible to manage our git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the jupyter-book more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
## Terminology
This is a (non-exhaustive) list of terminology that will be used in Git for local use.
- Repository: a collection of files and folders, along with a history of their changes and who made them.
- Commit: a snapshot of the current state of the repository.
- Staging: preparation of files to be committed. During staging, we propose files to be committed.
- Branch: a development line.
- Local: on your own computer.
- Remote: on someone elses computer.
- Pushing: uploading new commits to the remote repository.
- Pulling: downloading new commits from the remote repository to your local repository.
- Tracked (files): files that Git knows about and keeps track of their history.
- Untracked (files): files that Git does not yet know about.
In this section you will learn how to install Git locally. Courses on Git usually make use of the command line interface to do run Git, but this introduces a steep learning curve. Instead, using Git from VS Code / GitHub Desktop is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line.
## Installing Git
First, we need to install Git itself.
First, we need to install Git itself. Although this isn't strictly required when using GitHub Desktop
````{tab} Windows
````{tab} git on Windows
1. Go to [this webpage](https://git-scm.com/download/win) and download the correct version of Git for your system.
2. Execute the installer and go through it. You can leave all options to the default values, **but make sure the option "Git from the command line and also from 3rd-party software" is selected**. Without this option, we won't be able to use Git from VS Code.
3. Once the installation is finished, check if everything works. Open the start menu, then type `git`. From the search results, open the application `Git Bash`. This will open a terminal window, in which you can execute commands. Type in the command `git`, and execute it by pressing enter. If Git is installed correctly, you should see some sort of help page. If it outputs an error, then something may went wrong with the installation (you may have selected a wrong option).
````
````{tab} MacOS
````{tab} git on MacOS
Open up a terminal window (*Command + Space*, type in `terminal`). Then, type the command `git`. If Git has been installed already, it will output some help. If Git has not been installed, you will get a pop-up that looks something like this:
```{figure} ../images/install-Xcode-CLT.png
```
Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by exectuting `git` again.
Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by executing `git` again.
````
## Setting up SSH-keys
When we want to visit repositories on GitLab, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab with an SSH-key of our sytem, so that GitLab knows it is indeed us that are making the changes to the repository, removing the need to provide a password.
When we want to visit repositories on GitLab or GitHub, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab/GitHub with an SSH-key of our system, so that GitLab/GitHub knows it is indeed us that are making the changes to the repository, removing the need to provide a password. If you're only using GitHub and GitHub desktop, SSH-keys aren't strictly required, but it's still advised you set these up.
1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command:
@ -57,6 +42,8 @@ When we want to visit repositories on GitLab, we need to log in. The same holds
3. You will now be asked to enter a passphrase. You can give one, but you will be asked for it everytime you make a commit, so it's better to leave this field emtpy and use this key only for GitLab. After the command is done executing, it will generate two files: `id_ed25519` and `id_ed25519.pub`. The `.pub` file is the public part of the SSH-Key which we need.
`````{tab-set}
````{tab-item} continue on GitLab
4. Go to [GitLab](https://gitlab.tudelft.nl) and log in using your NetID. Click on your profile icon on the top-right of the page, then go to Preferences. In the menu on the left, go to SSH-Keys. You are now greeted with a screen that looks like this:
@ -77,6 +64,41 @@ When we want to visit repositories on GitLab, we need to log in. The same holds
Welcome to GitLab, <netid>!
````
````{tab-item} continue on GitHub
4. Go to [GitHub](https://github.com/) and log in. In the upper-right corner of any page, click your profile photo, then click Settings.
```{figure} https://docs.github.com/assets/cb-45016/mw-1440/images/help/settings/userbar-account-settings-global-nav-update.webp
:width: 200px
```
5. In the "Access" section of the sidebar, click SSH and GPG keys.
6. Click New SSH key or Add SSH key.
7. In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal laptop, you might call this key "Personal laptop".
8. Select the type of key: authentication
9. Navigate to the `id_ed25519.pub` file that we generated in step 2. Open the file with a text editor (Notepad on Windows, textEdit on Mac). Copy its contents and paste it in the 'Key' field.
```{note}
On MacOS, the `.ssh/` folder is hidden by default, so you won't be able to find it in finder. To show hidden files and folders, press **Command + Shift + .**
```
10. Click Add SSH key.
11. Now test the connection. Go to the terminal (Git Bash on windows) and type:
ssh -vT git@github.com
You should get a huge output, but somewhere at the end of that output it should say something like:
Welcome to GitLab, <username>!
````
`````
## Updating the local Git environment
The final step is to provide a username and email address to Git, so our commits can be identified. To do this, in the terminal (Git Bash on Windows) type in the following command for the username:
@ -87,9 +109,23 @@ And type the following command to set the email address:
git config --global user.email "<your TU Delft email>"
## Configuring Git Bash
## GitHub Desktop
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described in the {ref}`Getting Anaconda to work in terminal <vscode-setup-bash>`.
GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: [GitHub Desktop](https://desktop.github.com/)! While GitLab is a cloud-based version control system built around git, GitHub Desktop makes it possible to manage our git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the jupyter-book more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
## Terminology
This is a (non-exhaustive) list of terminology that will be used in Git for local use.
- Repository: a collection of files and folders, along with a history of their changes and who made them.
- Commit: a snapshot of the current state of the repository.
- Staging: preparation of files to be committed. During staging, we propose files to be committed.
- Branch: a development line.
- Local: on your own computer.
- Remote: on someone elses computer.
- Pushing: uploading new commits to the remote repository.
- Pulling: downloading new commits from the remote repository to your local repository.
- Tracked (files): files that Git knows about and keeps track of their history.
- Untracked (files): files that Git does not yet know about.
## More on GitLab

23
book/installation-and-setup/git.md Normal file
View file

@ -0,0 +1,23 @@
# Essential for collaboration: Git
```{admonition} User types
:class: tip
This page is useful for user type 3-5.
```
You'll need to interact with Git to collaborate on TeachBooks, but what is that thing?
## What is Git?
Git is a version control system (VCS), used by a wide variety of engineers and software developers to work on projects in parallel together. It provides multiple benefits such as tracking changes to files, working side by side with other people, and the ability to rollback to previous versions of files without losing track of newer changes. It is a free and open sources software.
### What is GitLab?
GitLab is a cloud-based version control system built around git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com.
### What is GitHub?
GitHub is the same service as GitLab, but it's part of a commercial company (Microsoft). It's the most well-known cloud-based git provider and provides a lot of functionalities for free for education. It also allows you to host websites on `github.io` eliminating the need for your own / TU Delft webserver, although you don't have full servercontrol.
### Additional lessons
Software carpentry offers git-lessons if you'd like to learn more than just it's specific use for TeachBooks. The lessons are available [online](https://swcarpentry.github.io/git-novice/) and TU Delft offers these as part of a [Software Carpentry workshop](https://www.tudelft.nl/library/research-data-management/r/training-evenementen/training-voor-onderzoekers/software-carpentry-workshops)

24
book/installation-and-setup/add_conda_to_path.md → book/installation-and-setup/git_bash_conda_vs-code.md
View file

@ -1,8 +1,16 @@
# Getting Anaconda to work in terminal
# Combining Git Bash, VS Code and Conda
```{admonition} User types
:class: tip
This page is useful for user type 5.
```
## Conda in Git Bash
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described here:
(vscode-setup-bash)=
````{tab} Windows - Git Bash (preferred)
There are two things to do before you can use conda in your Git Bash CLI (possibly in VS Code): 1) adding Anaconda to your PATH variables (as user, *not* as system/admin), and 2) setting up Anaconda to run on Git Bash.
There are two things to do before you can use conda in your Git Bash CLI: 1) adding Anaconda to your PATH variables (as user, *not* as system/admin), and 2) setting up Anaconda to run on Git Bash.
1. update the `PATH` variables:
* search for 'env' in the windows search to find the settings page. Anaconda doesn't recommend adding them to the system `PATH`, therefore when searching for the setting with the Windows search, so be careful to open **"edit environment variables for your account"**; do **not** "edit the system environment variables".
@ -48,4 +56,12 @@ then do the following:
```{note}
This is not the preferred installation method: Powershell has a different set of terminal commands that are not Unix-based, whereas Git Bash does. Since the vast majority of coding information and examples on the internet related to Jupyter and other open source projects uses Unix-based commands, we strongly recommend you always run Git Bash for your work in the terminal.
```
````
````
## Using Git Bash in VS Code (Windows only)
By default, Powershell is the default terminal used in VS Code. However, Git Bash is recommended because it provides Unix-like commands, making it much easier to find help on sites like Stack Exchange. It also works better with open source projects like Jupyter. Git Bash installs automatically with git which you'll learn in the next chapter; to set as default:
* Type `Ctrk+Shift+P` to open the command palette (it's also the top item in the "View" menu list)
* Start type "terminal default" and you will soon see and be able to select the setting "Terminal: Select Default Profile" (hit `Enter`)
* select Git Bash and hit "Enter" again to set as default
When creating a new terminal via the menu bar you should now automatically start with a Git Bash terminal. Note that if a Powershell terminal still opens by default, you can always create a new terminal and manually select Git Bash.

19
book/installation-and-setup/jupyter-book-setup.md
View file

@ -1,16 +1,15 @@
# Jupyter Book
# Build your book: JupyterBook
Jupyter Book is just a regular Python package, so it can be installed by using `pip` or `conda`:
```
pip install jupyter-book
```{admonition} User types
:class: tip
This page is useful for user type 5.
```
Nevertheless, it's always a good idea make a fresh `conda` environment when starting a new project.
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.
## Build a book
As soon as you've installed 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 one note, it's advised to 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 [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:
```
jupyter-book build <path-to-book> --all
@ -24,6 +23,7 @@ Once the build process is completed successfully, you will see the file location
:class: tip, dropdown
Bookmark the (local) file location for easy access!
```
(setup-local-server)=
## View the book using a local webserver
@ -31,5 +31,6 @@ Some features like JupyterLite and Grasple only work when a webserver serves the
1. Start a server from the command line with: `python -m http.server -b 127.0.0.1` (add ` &` if you want to keep using the terminal for other tasks).
2. Port 8000 is usually used by default, but depending on your OS it will tell you in the output.
3. To visit your site, just enter the address in your web browser, followed by a colon, and then the port number. By default, that would be: `127.0.0.1:8000`.
4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/`.
5. The JupyterLite consoles or Grasple iframe exercises should now work as well.
4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/` (if you've started this command from this folder you see the book immediately
5. You may need to reload the page once the rebuild is complete. You can do this on Chrome by right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. Or try `ctrl`+`F5`\n"
6. All interactive features like the JupyterLite consoles, Grasple/H5p iframe exercises, Sphinx-thebe python interactivity and HTML/Javascript elements should now work as well.

45
book/installation-and-setup/overview.md
View file

@ -1,43 +1,12 @@
# Installation and setup for different types of users
# Install & authenticate required software
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.
Now that the types of users have been explained, you might have an idea which type corresponds to you!
1. **Students providing feedback on the published website**. <br>
<img src="figures/type 1.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher.
<br style="clear:both;">
2. **Colleague providing feedback on the draft website**. <br>
In a similar manner, colleages and team members can leave content related comments on the webiste through that extension. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues.
3. **Colleague making adjustments in GitLab using single text editor**. <br>
This type of user requires only very basic knowledge in GitLab in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab.
4. **Colleague making text adjustments 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 non-interactive content locally**. <br>
This user has more knowledge in GitLab 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. The tricky part however is implementing interactive features in the book as they definitely require more knowledge on implementation and testing using a local python server or in the draft version online.
6. **Colleague making adjustments to all content locally**. <br>
<img src="figures/type 5.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
This user has an understanding of GitLab and can independently make changes on the website built through Jupyter Books. Moreover they have an understanding of various extensions that allows them to make the pages interactive for the student.
<br style="clear:both;">
**Overview required software**
Now that the types of users have been explained, you might have an idea which type corresponds to you! <br>
The following table will link the relevant installation and setup steps for you.
|<div style="width:120px">User Types</div>|<div style="width:400px">Relevant Sections</div>|<div style="width:150px">Installation</div>|
|User Types|Required actions|<div style="width:200px">Installation</div>|
|:---:|:---|:---|
| Type 1<br>Type 2 | No software needed!<br>Just open your interactive book and navigate to the extension | [Extension Tutorial](extension.md) |
| Type 3 | Understanding Git & GitLab | [Git & GitLab](git-setup.md) |
| Type 4 | Understanding Git & GitLab<br>Edit using VS Code<br>Local Git with VS Code / GitHub Desktop| [Git & GitLab](git-setup.md)<br>[VS Code](vscode-setup.md)<br>[How do I use git locally?](git-setup_local.md) |
| Type 5 | Understanding Git & GitLab<br>Edit using VS Code<br>Local Git with VS Code / GitHub Desktop<br>Anaconda<br>Using Anaconda in terminal<br>Working with directories<br>Python Environments<br>Python package: Jupyter book | [Git & GitLab](git-setup.md)<br>[VS Code](vscode-setup.md)<br>[How do I use git locally?](git-setup_local.md)<br>[Anaconda](anaconda.md)<br>[Anaconda in terminal](add_conda_to_path.md)<br>[Working directories](working-directory.md)<br>[Environments](environments.md)<br>[Jupyter Book](jupyter-book-setup) |
| Type 6 | Understanding Git & GitLab<br>Edit using VS Code<br>Local Git with VS Code / GitHub Desktop<br>Anaconda<br>Using Anaconda in terminal<br>Working with directories<br>Python Environments<br>Python package: Jupyter book <br> Extensions to create interactive features! | [Git & GitLab](git-setup.md)<br>[VS Code](vscode-setup.md)<br>[How do I use git locally?](git-setup_local.md)<br>[Anaconda](anaconda.md)<br>[Anaconda in terminal](add_conda_to_path.md)<br>[Working directories](working-directory.md)<br>[Environments](environments.md)<br>[Jupyter Book](jupyter-book-setup) <br> [Features](../features/overview.md) |
| Type 1<br>Type 2 | Review book | No software needed! Just open your interactive book online and give review in the way you're asked to do|
| Type 3 | Edit single files online | No software needed! But you'll interact with Git, which might be a new thing for you |
| Type 4 | Editing text<br>Git| VS Code<br>GitHub Desktop / Git in VS Code |
| Type 5 | Editing text<br>Git<br>Managing code-related software<br>Build your book | VS Code<br>GitHub Desktop / Git in VS Code<br>Anaconda<br>Jupyter Book |

29
book/installation-and-setup/user_types.md Normal file
View file

@ -0,0 +1,29 @@
# 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.
1. **Students providing feedback on the published website**. <br>
<img src="figures/type 1.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
There are multiple tools of providing feedback in the build book:
- 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)
- 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. Those comments are converted to issues on GitHub for the editors to handle.
<br style="clear:both;">
2. **Colleague providing feedback on the draft website**. <br>
In a similar manner as students, colleages and team members can leave content related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues.
3. **Colleague making adjustments to single files in GitLab/GitHub using single text editor**. <br>
This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab/GitHub.
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>
<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.
<br style="clear:both;">

27
book/installation-and-setup/vscode-setup.md
View file

@ -1,4 +1,9 @@
# VS Code
# Editing text: VS Code
```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```
VS Code is a text editor with some extra features, such as integrated source control and a file browser. Moreover, extensions are available to add functionality to VS Code.
@ -10,15 +15,11 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal
When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended:
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering.
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.
- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files).
## Using the Terminal in VS Code (Windows only)
By default, Powershell is the default terminal used in VS Code. However, Git Bash is recommended because it provides Unix-like commands, making it much easier to find help on sites like Stack Exchange. It also works better with open source projects like Jupyter. Git Bash installs automatically with git which you'll learn in the next chapter; to set as default:
* Type `Ctrk+Shift+P` to open the command palette (it's also the top item in the "View" menu list)
* Start type "terminal default" and you will soon see and be able to select the setting "Terminal: Select Default Profile" (hit `Enter`)
* select Git Bash and hit "Enter" again to set as default
When creating a new terminal via the menu bar you should now automatically start with a Git Bash terminal. Note that if a Powershell terminal still opens by default, you can always create a new terminal and manually select Git Bash.
- User type 4-6:
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.
- [Spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker for source code and text
- User type 5-6
- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files).
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering.
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - Your AI pair progammer
- [Jupyter Cell Tags](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-cell-tags) - Jupyter Cell Tags support

31
book/installation-and-setup/working-directory.md
View file

@ -1,31 +0,0 @@
# Navigate to your working directory
You will need to know this to set up environments from a text-based file.
The essential command is `cd FILE_PATH`, which will navigate the terminal window to the directory at `FILE_PATH`. Note that although `cd` works on both Windows and Mac, many command line commands are different between the two.
````{tab} Windows
1. Open the folder you wish to use as your working directory in the File Explorer
2. In the bar near the top you will see the folder address; you may need to click in the window to see the file path (i.e., the tree of folders separated by forward slashes, `/`)
3. Select the entire path and copy it (CTRL+C or right-click, “copy address as text”)
4. You can now paste this path into the Anaconda Prompt after the `cd` command
5. Confirm you are in the right place by inspecting the path listed in your prompt (it should typically start with be `C:\ ...` and end wit `>`)
6. You can also inspect the contents of the directory by executing `dir`
Alternative
1. Open the folder you wish to use as your working directory in the File Explorer
2. Right-click the folder and click `Git bash here`
3. Confirm you are in the right place by inspecting the path listed in your prompt (it should typically start with be `C:\ ...` and end wit `>`)
4. You can also inspect the contents of the directory by executing `dir`
````
````{tab} Mac
1. Find the folder you wish to use as your working directory
2. Right-click and select Get Info
3. Hold down the Alt (Option) key; the menu items will change\
4. Select Copy … As Pathname
5. You can now paste this path into the Terminal after the `cd` command
6. Confirm you are in the right place by executing the command `pwd`
7. You can also inspect the contents of the directory by executing ls (that’s a lower case “L”)
8. Go here to see the source of this tip, along with screenshots.
````

4
book/intro.md
View file

@ -1,6 +1,6 @@
# Jupyter Book Manual
# 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/).
## Contact
If you encouter 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 Caspar Jungbacker or Julie Kirsch at TeachBooks@tudelft.nl.

120
book/workflows/branches.md
View file

@ -1,4 +1,4 @@
# Branches
# Create your own version (branching, cloning, pulling)
Branches are a very useful feature of Git. Branches allow you to work on multiple versions of your codebase simultaneously; you create a copy of your codebase, on which you can work independently of the main codebase. The main branch is the default branch. The content on this branch will be the most up to date version of the book. Therefore, new branches, which are made to add or fix some content in the book, are usually cloned from the main branch. This has many advantages compared to making the edits immediately in the main branch. Some advantages of working with branches are:
@ -9,9 +9,15 @@ This systematic workflow guarantees that editing the book goes smoothly.
The act of making a new branch from an existing one is called *branching*. Usually, you want to branch from the `main` branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the *source* branch.
`````{tab-set}
````{tab-item} Branching in GitLab
**Create your own version by ...**
`````````{tab-set}
````````{tab-item} ... user type 3
**... by directly creating your own version (branching) or selecting existing version in ...**
`````{tab-set}
````{tab-item} ... GitLab
1. On GitLab, navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
```{figure} ../images/gitlab-branch.png
@ -28,19 +34,77 @@ Click the highlighted button to make a new branch.
We're making a new branch called `chapter-2` from the `main` branch.
```
3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`.
3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch.
```{figure} ../images/gitlab-new-branch-repo.png
:name: new-branch-repo
The circled menu is the branch selection menu.
```
````
````{tab-item} Branching in GitHub
...
````{tab-item} ... GitHub
```{error} To be written
```
````
````{tab-item} Branching locally with Git in VS Code
4. The final step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`).
`````
````````
````````{tab-item} ... user type 4 and 5
**... for ...**
```````{tab-set}
``````{tab-item} ... repository opened for first time
**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch) from ...**
`````{tab-set}
````{tab-item} ... GitLab
1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
The cloning menu.
```
````
````{tab-item} ... GitHub
```{error} To be written
```
````
````{tab-item} ... GitHub using GitHub Desktop
```{error} To be written
```
````
`````
**... with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
```{figure} ../images/vscode-welcome.png
:name: vscode-welcome
The VS Code welcome screen.
```
3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open".
4. You now have a local copy of the repository.
5. The final step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`).
```{figure} ../images/git-branch-menu-main.png
:name: git-branch-menu-main
@ -50,12 +114,44 @@ Location of the branch menu.
```{figure} ../images/git-branch-selection-menu.png
:name: git-branch-selection-menu
The branch selection menu, where our new branch has shown up.
```
The branch selection menu, where our new branch has shown up. From this menu you can also select (checkout in git terms) another existing branch.
````
````{tab-item} Branching locally with GitHub Desktop
...
````{tab-item} ... GitHub Desktop
```{error} To be written
```
````
`````
``````
``````{tab-item} ... previously opened repository
**by updating your repository (pulling) and creating your own version (branching) or select existing version (checkout branch) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
```{error} To be written
```
````
````{tab-item} ... GitHub Desktop
```{error} To be written
```
````
`````
``````
```````
````````
`````````
Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.

17
book/workflows/check_changes_online.md Normal file
View file

@ -0,0 +1,17 @@
# Check changes online
Now that you've pushed your changes online, it's time to check the change in the online build book to make sure that your changes are processed correctly. For this step it is assumed you're using TeachBook's GitHub actions or TeachBook's GitLab pipeline.
`````{tab-set}
````{tab-item} In GitLab
At the moment this is not possible, but the workflow will soon be the same as for GitHub.
````
````{tab-item} In GitHub
- Wait for the action to finish
- Visit the website of your build book
```{error} To be written
```
`````
You can keep on [editing](edit_book) and checking your changes until you're satisfied and ready for a review by a colleague.

94
book/workflows/collaboration.md
View file

@ -1,4 +1,4 @@
# Collaborative book-editing using Git
# Collaborative book-editing
As previously mentioned there are multiple platforms that can host Git repositories which are extremely useful for collaboration on text-based files. Here we will elaborate on two: GitLab and GitHub both in the online environment and locally on your device.
@ -12,4 +12,94 @@ Globally, the steps involved are as follows:
- Committing a collection of changes
- If working on a repository locally: pushing your changes
5. Reviewing and merging changes in a merge request
6. Publishing the changes to the published version of the book
6. Publishing the changes to the published version of the book
```{admonition} User types
:class: tip
This page is useful for user type 3, 4 and 5.
```
A jupyter book is composed out of many files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch.
We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `gitlab.tudelft.nl` or `github.com/teachbooks`.
The steps involved are as follows:
1. **Assign task to yourself (milestones, issues)**
2. **Create your own version of the book by**
```````{tab-set}
``````{tab-item} ... user type 3
**... by directly creating your own version (branching) or selecting existing version:**
- branching
``````
``````{tab-item} ... user type 4 and 5
**... for ...**
`````{tab-set}
````{tab-item} ... repository opened for first time
**... by opening the repository locally (cloning) and creating your own version (branching) or select existing version (checkout branch):**
- cloning
- branching / checkout branch
````
````{tab-item} ... previously opened repository
**... by updating your repository (pulling) and creating your own version (branching) or select existing version (checkout branch):**
- pulling
- branching / checkout branch
````
`````
``````
```````
3. **Edit the book by ...**
```````{tab-set}
``````{tab-item} ... user type 3
**... by directly adding changes on a single file to Git-timeline (committing):**
- adding or making changes to single file
- committing
``````
``````{tab-item} ... user type 4
... on ...
`````{tab-set}
````{tab-item} ... brand new version (branch)
**... by making changes on a single / multiple file(s), selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
- adding or making changes to file(s)
- staging
- committing
- pushing
````
````{tab-item} ... existing version (branch)
**... by regularly obtaining updates from colleagues from GitLab/GitHub (pulling), solving potential incompatible changes (merge conflicts), making changes on a single / multiple file(s), selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
- pulling
- solving merge conflicts
- adding or making changes to file(s)
- staging
- committing
- pushing
````
`````
``````
``````{tab-item} ... user type 5
... on ...
`````{tab-set}
````{tab-item} ... brand new version (branch)
**... by making changes on a single / multiple file(s), checking changes locally, selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
- adding or making changes to file(s)
- checking changes locally
- staging
- committing
- pushing
````
````{tab-item} ... existing version (branch)
**... by regularly obtaining updates from colleagues from GitLab/GitHub (pulling), solving potential incompatible changes (merge conflicts), making changes on a single / multiple file(s), checking changes locally, selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing):**
- pulling
- solving merge conflicts
- adding or making changes to file(s)
- checking changes locally
- staging
- committing
- pushing
````
``````
```````
4. **Check changes online**
5. **Repeat steps 3 and 4 until you're satisfied**
6. **Reviewing (merge request), (eventually repeat steps 3 and 4) and combine (merging) your version with main draft version of book**
7. **Publish changes to student version of the book (merge request)**

257
book/workflows/edit_book.md
View file

@ -1,34 +1,57 @@
# Editing the book
# Edit (merge conflicts, staging, committing, pushing)
A jupyter book is composed out of many markdown files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch.
Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes, and we've checked out this branch (make sure this is really the case by checking the name of the current branch in the bottom-left corner of your VS Code window!).
## Pulling
If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch, pull changes from the remote repository on GitHub / GitLab into your local folder.
Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes.
**Edit files by ...**
`````````{tab-set}
````````{tab-item} ... user type 3
**... by directly adding changes on a single file to Git-timeline (committing) in ...**
`````{tab-set}
````{tab-item} Pulling changes using Git in VS Code
...
````{tab-item} ... GitLab
Make changes to file in text editor...
or add new file by text or upload
```{error} To be written
```
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} Pulling changes using GitHub Desktop
...
````{tab-item} ... GitHub
Make changes to file in text editor...
or add new file by text or upload
```{error} To be written
```
click commit in single text editor ...
```{error} To be written
```
````
`````
## Staging
````````
````````{tab-item} ... user type 4
**... for ...**
```````{tab-set}
``````{tab-item} ... brand new version (branch)
**... by making changes on a single / multiple file(s), selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing) with ...**
`````{tab-set}
````{tab-item} Staging in GitLab
In GitLab staging doesn't exist, just edit a file and you can directly commit it.
...
````
````{tab-item} Staging in GitHub
In GitHub staging doesn't exist, just edit a file and you can directly commit it.
...
````
````{tab-item} Staging using Git in VS Code
````{tab-item} ... Git in VS Code
```{error} To be written
```
Make some changes in for example VS Code and save them.
Select files ready to be added to Git-timeline (staging)
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
@ -38,23 +61,7 @@ The new file appears in the Source Control menu.
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
````
````{tab-item} Staging using GitHub Desktop
...
````
`````
## Committing
Now that we've made some change, we need to add them to our git-timeline.
`````{tab-set}
````{tab-item} Committing in GitLab
...
````
````{tab-item} Committing in GitHub
...
````
````{tab-item} Committing using Git in VS Code
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
@ -62,30 +69,170 @@ Next, in the field that says "Message", write a short description of the changes
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
````
````{tab-item} Committing using GitHub Desktop
...
````
`````
```{tip}
Unlike this example, you do not have to stage and commit every file individually. In a real case, a chapter may consist of multiple files (and images!), and it makes sense to add them in the same commit.
```
## Pushing the changes
Are we done now? Yes, if you've made all your changes on GitLab / GitHub. However, no! if you did that locally! Up to now, we have only made changes and committed to the *local* copy of the repository. We still need to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab), so that others can see our changes and interact with them.
`````{tab-set}
````{tab-item} Committing using Git in VS Code
In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} ... GitHub Desktop
```{error} To be written
```
Make some changes in for example VS Code and save them.
The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)...
```{error} To be written
```
Add changes to Git-timeline locally (committing)
```{error} To be written
```
Add changes to GitHub/GitLab (pushing)
```{error} To be written
```
````
`````
``````
``````{tab-item} ... existing version (branch)
**... by regularly obtaining updates from colleagues from GitLab/GitHub (pulling), solving potential incompatible changes (merge conflicts), making changes on a single / multiple file(s), selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that?
```{error} To be written
```
````
````{tab-item} Committing using GitHub Desktop
...
````{tab-item} ... GitHub Desktop
text..
```{error} To be written
```
````
`````
`````
``````
```````
````````
````````{tab-item} User type 5
```````{tab-set}
``````{tab-item} ... brand new version (branch)
**... by making changes on a single / multiple file(s), checking changes locally, selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
```{error} To be written
```
Make some changes in for example VS Code and save them.
build book locally and eventually startup python server...
```{error} To be written
```
Select files ready to be added to Git-timeline (staging)
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
```{figure} ../images/git-new-file.png
The new file appears in the Source Control menu.
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} ... GitHub Desktop
```{error} To be written
```
Make some changes in for example VS Code and save them.
The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)...
```{error} To be written
```
Add changes to Git-timeline locally (committing)
```{error} To be written
```
Add changes to GitHub/GitLab (pushing)
```{error} To be written
```
````
`````
``````
``````{tab-item} ... existing version (branch)
**... by regularly obtaining updates from colleagues from GitLab/GitHub (pulling), solving potential incompatible changes (merge conflicts), making changes on a single / multiple file(s), checking changes locally, selecting changes to be added to the Git-timeline (staging), adding those to the Git-timeline (committing) and adding those changes to GitLab/GitHub (pushing) with ...**
`````{tab-set}
````{tab-item} ... Git in VS Code
**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)**
If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that?
```{error} To be written
```
````
````{tab-item} ... GitHub Desktop
text..
```{error} To be written
```
````
`````
``````
```````
````````
`````````

BIN
book/workflows/figures/GitHub_desktop_fork.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
book/workflows/figures/action.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
book/workflows/figures/create_new_repository.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 45 KiB

0
book/workflows/figures/Issues.PNG → book/workflows/figures/issues_new.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 77 KiB

After

Width:  |  Height:  |  Size: 77 KiB

Before After
Before After

BIN
book/workflows/figures/set_up_pages.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 87 KiB

BIN
book/workflows/figures/use_github_pages_website.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 76 KiB

BIN
book/workflows/figures/use_template.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 83 KiB

71
book/workflows/githubtemplate.md
View file

@ -1,47 +1,58 @@
# Example using our GitHub template
# Your first TeachBook using the template
This page shows you how as an example how to create your own Jupyter Book. It including making an edit to a predefined book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git.
```{admonition} User types
:class: tip
This page is useful for user type 3, 4 and 5.
```
To get started making your Jupyter Book with our functionalities, fork our template book https://github.com/TeachBooks/template :
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.
![alt text](../images/image.png)
`````{tab-set}
````{tab-item} GitHub template
Fill in a repository name, this name will be used in the future url of your book:
1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template:
![alt text](../images/image-1.png)
```{figure} figures/use_template.png
:name: use-template
```
Set up the build of your website using GitHub pages by selecting under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`:
2. Fill in a repository name, this name will be used in the future url of your book:
![alt text](../images/image-2.png)
```{figure} figures/create_new_repository.png
:name: create_new_repository
```
Enable the predefined workflow to publish your book under `Actions` - `I understand my workflows, go ahead an enable them`:
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`:
![alt text](../images/image-3.png)
```{figure} figures/set_up_pages.png
:name: activate_pages
```
Edit a file under `Code` - `book` - A file of your choice - `Edit in place`, in the example below `book/intro.md` is edited:
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`
![alt text](../images/image-5.png)
```{figure} figures/use_github_pages_website.png
:name: github_pages_as_website
```
Make your edit and `Commit changes` to `main` branch:
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`:
![alt text](../images/image-6.png)
![alt text](../images/image-7.png)
Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under `Actions` - `All wokflows`:
![alt text](../images/image-8.png)
When the workflow has finished, visit your build book at `https://<username>.github.io/<repository_name>` (case sensitive). For our example it is: [https://dummystudent-Tom.github.io/My_own_book](https://dummystudent-Tom.github.io/My_own_book) :
![alt text](../images/image-9.png)
---
It is possible to have multiple versions of a book published at once, by creating another Git branch (e.g. `draft` or `dev`).
For each branch, the respective book is published at `https://<username>.github.io/<bookname>/<branchname>`.
Technical note: for convenience, just `.../<bookname>/` redirects to `.../<bookname>/book/`, which is itself an alias (a symlink) for
`.../<bookname>/main/`.
```{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

17
book/workflows/merge_request.md
View file

@ -1,15 +1,15 @@
# Reviewing and merging changes
# Reviewing and combine versions (merge / pull request, merging)
Merging a branch into the main branch is also good moment to let a team-member review the content. This is done in the merge-request. By assigning a colleague to review your branch you can check the quality of your new content.
Merging a branch into the main branch is also good moment to let a team-member review the content. By assigning a colleague to review your branch you can check the quality of your new content.
```{note}
There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch.
```
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch.
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practice to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts are solved before, we'll now continue this example with the following merge of our branch into `main`.
`````{tab-set}
````{tab-item} Committing using GitLab
````{tab-item} In GitLab
1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository.
@ -41,7 +41,12 @@ The finished merge request.
```
````
````{tab-item} Committing using GitHub
...
````{tab-item} In GitHub
```{error} To be written
```
````
`````

15
book/workflows/milestones_issues.md
View file

@ -1,4 +1,4 @@
# Milestones & Issues
# Assign task to yourself (milestones, issues)
In a repository, team members can define Milestones and Issues. Milestones are used to track the overall progress of the project to make sure that deadlines are met. A milestone can group many issues, which are individual tasks that need to be finished in order to reach the milestone.
@ -12,17 +12,22 @@ An issue is built up of the following attributes:
Every team member can create issues when they think of a task that would improve the book.
The following tabs explain where the Issues can be found in GitLab and GitHub.
**Make and assign task to yourself (issues) in ...**
`````{tab-set}
````{tab-item} ... GitLab
`````{tab-set}
````{tab-item} GitLab
The issues in GitLab can be found in your repositery in the left bar.
<img src="figures/Issues.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
![issues](figures/issues_new.png)
You can create an issue by clicking on the blue `New Issue` button in the top right corner. This will lead you to this window where you can specify all attributes we mentioned before!
<img src="figures/New_Issue_GitLab.png" alt="New Issue" width="600" style="display:block; margin-left:auto; margin-right:auto;"> <br>
![new issue](figures/New_Issue_GitLab.png)
````
````{tab-item} GitHub
@ -38,6 +43,10 @@ Clicking on `Issues` will open up the page with all the issues on this repositer
Finally, by clicking the green `New Issue` button you can create a new issue and specify all the attributes we mentioned before!
<img src="figures/New_Issue_GitHub2.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
````{tab-item} ... GitHub
```{error} To be written
```
````
`````

10
book/workflows/overview.md
View file

@ -1,10 +0,0 @@
# Workflows
- what does the publish branch do?
- what is a pipeline
This coming page suggests a workflow how to collaborate using Git! Every team might have a different workflows but this workflow is shown as an example and is used in the MUDE course in CEG and by the TeachBooks team.<br>
There are two web-based platforms that host Git repositories: GitLab and GitHub. You might have read about GitHub Desktop that we are using to manage local repositories. GitLab and GitHub have similar features and are both widely used by the open source community. The main difference that is relevant for TeachBooks is that GitHub allows to host websites online without a server whereas GitLab needs a server. TU Delft has their own server which is why we use `tudelft.gitlab.nl`.
Now that you understand how to collaborate in git it is time to get started on your own book. The end of this chapter provides a [tutorial](githubtemplate.md) on how to fork our template book. By forking you are essentially creating an independent copy of the template repository in your own GitLab or GitHub account.

9
book/workflows/publish.md
View file

@ -1,4 +1,7 @@
# Publishing your book
# Publish to students
Once the book is ready to be published, a static website can be created through GitLab. (Need more info on that/Are we using gitlab pages?)
If your repository is located in the [TeachBooks](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, you will see that it already has a branch called `publish`. This branch is where the student version of your book should go. The idea behind this is that the student version of your book should only change a few times per year at most (and certainly not right before an exam!) to prevent confusion. This way, you can still make frequent changes to the `main` branch.
For this step it is assumed you’re using TeachBook’s GitHub actions or TeachBook’s GitLab pipeline.
Until now, you merged your changes to branch `main`, but you might see a branch called `publish` as well. This branch is where the student version of your book should go. The idea behind this is that the student version of your book should only change a few times per year at most to prevent confusion. This way, you can still make frequent changes to the `main` branch.
To publish your changes to the student version, simply repeat the next step but now from `main` to `publish`