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 'main' into 'publish'

Browse source 
Main

See merge request interactivetextbooks-citg/jupyter-book-manual!65
This commit is contained in:
Tom van Woudenberg 2024-04-11 14:18:46 +02:00
commit 06c0410106
25 changed files with 515 additions and 364 deletions
Download patch file Download diff file Expand all files Collapse all files

7
book/_toc.yml
View file

@ -5,15 +5,13 @@ 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/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/githubtemplate
- file: workflows/collaboration
@ -22,6 +20,7 @@ parts:
- file: workflows/repositories
- file: workflows/branches
- file: workflows/edit_book
- file: workflows/check_changes_online
- file: workflows/merge_request
- file: workflows/publish
- caption: Features

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.

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:
```

5
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 [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.

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

@ -1,11 +1,15 @@
# Anaconda
# Managing code-related software: Anaconda
```{admonition} User types
:class: tip
This page is useful for user type 5-6.
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. You can download the installation files [here](https://www.anaconda.com/download).
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:
@ -22,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).
### 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`.
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!
### 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!

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

@ -1,121 +0,0 @@
# Creating python environments
```{admonition} User types
:class: tip
This page is useful for user type 5-6.
```
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 --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).
## 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!

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

@ -1,24 +0,0 @@
# What is Git and GitLab?
```{admonition} User types
:class: tip
This page is useful for user type 3-6.
```
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.

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

@ -1,53 +1,33 @@
# How do I use Git locally?
# Git: GitHub Desktop / Git in VS Code
```{admonition} User types
:class: tip
This page is useful for user type 4-6.
This page is useful for user type 4 and 5.
```
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.
## 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:
@ -62,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:
@ -82,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:
@ -92,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)

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

@ -1,14 +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-6.
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".
@ -54,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.

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

@ -1,21 +1,15 @@
# Jupyter Book
# Build your book: JupyterBook
```{admonition} User types
:class: tip
This page is useful for user type 5-6.
This page is useful for user type 5.
```
Jupyter Book is just a regular Python package, so it can be installed by using `pip` or `conda`:
```
pip install jupyter-book
```
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
@ -29,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

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

@ -1,13 +1,12 @@
# Installation for book reviewers and editors
# Install & authenticate required software
Now that the types of users have been explained, you might have an idea which type corresponds to you!
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 online and give review in the way you're asked to do| |
| 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 |

14
book/installation-and-setup/user_types.md
View file

@ -14,18 +14,16 @@ Different types of users will interact with the website or the Jupyter Books dif
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 in GitLab/GitHub using single text editor**. <br>
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 locally**. <br>
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 non-interactive content locally**. <br>
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. 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>
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 an understanding of GitLab/Github 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.
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;">
<br style="clear:both;">

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

@ -1,8 +1,8 @@
# VS Code
# Editing text: VS Code
```{admonition} User types
:class: tip
This page is useful for user type 4-6.
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.
@ -15,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

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

@ -1,37 +0,0 @@
# Navigate to your working directory
```{admonition} User types
:class: tip
This page is useful for user type 5-6.
```
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.
````

51
book/workflows/branches.md
View file

@ -1,4 +1,4 @@
# Branches
# Create your own version
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,8 +9,11 @@ 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} User type 3
`````{tab-set}
````{tab-item} Branching in GitLab
````{tab-item} In 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".
@ -36,10 +39,41 @@ We're making a new branch called `chapter-2` from the `main` branch.
The circled menu is the branch selection menu.
```
````
````{tab-item} Branching in GitHub
...
````{tab-item} In GitHub
```{error} To be written
```
````
````{tab-item} Branching locally with Git in VS Code
`````
``````
``````{tab-item} User type 4 and 5
### Obtain newest version from online repository
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.
`````{tab-set}
````{tab-item} With Git in VS Code
```{error} To be written
```
````
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
### Create your own version
`````{tab-set}
````{tab-item} With Git in VS Code
```{error} To be written
```
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`).
```{figure} ../images/git-branch-menu-main.png
:name: git-branch-menu-main
@ -53,9 +87,12 @@ Location of the branch menu.
The branch selection menu, where our new branch has shown up.
```
````
````{tab-item} Branching locally with GitHub Desktop
...
````{tab-item} With 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.

45
book/workflows/collaboration.md
View file

@ -2,19 +2,40 @@
```{admonition} User types
:class: tip
This page is useful for user type 3-6.
This page is useful for user type 3, 4 and 5.
```
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.
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.
Globally, the steps involved are as follows:
1. Define issue to work on
2. Open the files of the repository online or clone the repository to work on it locally
3. Create a branch for your changes
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
2. Open the files of the repository online or locally
3. Create your own version of the book
4. Edit the book by:
- Pulling remote changes from others
- Staging your changes
- Commit a collection of changes
- If working on a repository locally: pushing your changes
5. Reviewing and merging changes in a merge request
6. Publish changes to published version of book
`````{tab-set}
````{tab-item} User type 3
- Add or make changes to a file
- Share changes with others in Git-timeline
````
````{tab-item} User type 4
- Eventually solve issues with combining versions
- Add or make changes to a file(s)
- Select files ready to be added to Git-Timeline
- Share changes with others in Git-timeline
- Pushing your changes
````
````{tab-item} User type 5
- Eventually solve issues with combining versions
- Add or make changes to a file(s)
- Select files ready to be added to Git-Timeline
- Check changes in book locally
- Share changes with others in Git-timeline
- If working on a repository locally: pushing your changes
````
`````
5. Check changes online
6. Repeat steps 4 and 5 until you're satisfied
7. Reviewing, (eventually repeat steps 4 and 5) and combine your version with main draft version of book
8. Publish changes to student version of the book

126
book/workflows/edit_book.md
View file

@ -1,34 +1,48 @@
# Editing the book
# Edit
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.
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!).
## Add or make changes to a file(s)
```````{tab-set}
``````{tab-item} User type 3
## Pulling
Make changes to file in text editor...
or add new file by text or upload
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.
```{error} To be written
```
``````
``````{tab-item} User type 4 and 5
### Eventually solve issues with combining versions
First make sure you update your branch so that you've the most up-to-date version. If you collaborate on this branch, you get the updates from your colleagues as well. This might lead into a merge conflict. How to solve that?
`````{tab-set}
````{tab-item} Pulling changes using Git in VS Code
...
````{tab-item} With Git in VS Code
```{error} To be written
```
````
````{tab-item} Pulling changes using GitHub Desktop
...
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
## Staging
### Make actual changes
```{error} To be written
```
Make some changes in for example VS Code and save them.
### Select files ready to be added to Git-Timeline
`````{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} With Git in VS Code
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:
@ -39,22 +53,52 @@ 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
...
````{tab-item} With GitHub Desktop
The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)...
```{error} To be written
```
````
`````
## Committing
Now that we've made some change, we need to add them to our git-timeline.
``````
```````
## Check changes in book locally
```````{tab-set}
``````{tab-item} User type 3 and 4
Not possible, unless you want to be a user type 5. Otherwise you'll see your changes later on online.
``````
``````{tab-item} User type 5
build book locally and eventually startup python server...
```{error} To be written
```
``````
```````
## Share changes with others in Git-timeline
```````{tab-set}
``````{tab-item} User type 3
`````{tab-set}
````{tab-item} Committing in GitLab
...
````{tab-item} In GitLab
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} Committing in GitHub
...
````{tab-item} In GitHub
click commit in single text editor ...
```{error} To be written
```
````
````{tab-item} Committing using Git in VS Code
``````
``````{tab-item} User type 4 and 5
Now we're going the share our changes in the Git-timeline with a *commit* and to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab/GitHub), so that others can see our changes and interact with them.
`````{tab-set}
````{tab-item} 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
@ -63,29 +107,19 @@ 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} Using GitHub Desktop
```{error} To be written
```
````
````{tab-item} Committing using GitHub Desktop
...
````
`````
`````
``````
```````

7
book/workflows/githubtemplate.md
View file

@ -1,8 +1,8 @@
# Your first TeachBook using template
# Your first TeachBook using the template
```{admonition} User types
:class: tip
This page is useful for user type 3-6.
This page is useful for user type 3, 4 and 5.
```
This page shows you how as an example how to start your own Jupyter Book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book.
@ -50,7 +50,8 @@ To learn more about how we do this, please see the [GitHub Actions documentation
````
````{tab-item} GitLab template
Will follow
```{error} To be written
```
````
`````

15
book/workflows/merge_request.md
View file

@ -1,6 +1,6 @@
# Reviewing and merging changes
# Reviewing and combine versions
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.
@ -9,7 +9,7 @@ There is a slight difference in terminology between GitLab and GitHub. GitLab us
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch.
`````{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
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,19 +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.
`````{tab-set}
````{tab-item} Issues in GitLab
````{tab-item} In GitLab
The issues in GitLab can be found on this page:
<img src="figures/Issues.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
![issues](figures/issues.png)
You can create an issue by clicking on the blue `New Issue` button in the top right corner.
<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} Issues in GitHub
...
````{tab-item} In GitHub
```{error} To be written
```
````
`````

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`

46
book/workflows/repositories.md
View file

@ -1,14 +1,19 @@
# Open files online / clone files
We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (markdown) 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`.
# Open files
If you'd like to work on your book locally, you need to clone your book.
```````{tab-set}
``````{tab-item} User type 3
Find your file on GitLab/GitHub ...
```{error} To be written
```
### Cloning a repository
``````
``````{tab-item} User type 4 and 5
## Find source in online repository
`````{tab-set}
````{tab-item} Cloning repository from GitLab
Here's how you do it with VS Code:
````{tab-item} From 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".
@ -19,19 +24,23 @@ The cloning menu.
```
````
````{tab-item} Cloning repository from GitHub
...
````{tab-item} From GitHub
```{error} To be written
```
````
````{tab-item} Cloning repository from GitHub using GitHub Desktop
...
````{tab-item} From GitHub using GitHub Desktop
```{error} To be written
```
````
`````
Now that we've obtained the source, we can set up the files locally:
## Open the files locally
`````{tab-set}
````{tab-item} Cloning repository with Git in VS Code
````{tab-item} With 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
@ -45,7 +54,12 @@ The VS Code welcome screen.
4. You now have a local copy of the repository.
````
````{tab-item} Cloning repository with GitHub Desktop
....
````{tab-item} With GitHub Desktop
```{error} To be written
```
````
`````
`````
``````
```````