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 'release' into apa-style

Browse source
This commit is contained in:
Robert Lanzafame 2024-12-06 14:23:02 +05:30 • committed by GitHub
commit 080df45855
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 158 additions and 377 deletions
Download patch file Download diff file Expand all files Collapse all files

6
book/_config.yml
View file

@ -1,8 +1,6 @@
title: TeachBooks Manual
author: TeachBooks Team, built with <a href="https://teachbooks.io/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
logo: images/Logo_without_background.png
execute:
execute_notebooks: 'off'
@ -27,6 +25,9 @@ sphinx:
use_thebe_lite: true
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb","**/*.gif","**/*.txt","**/*.json",]
html_theme_options:
logo:
image_light: TB_logo.png
image_dark: TB_logo_dark.png
repository_url: "https://github.com/TeachBooks/manual/"
path_to_docs: "book"
repository_branch: "release"
@ -37,6 +38,7 @@ sphinx:
thebe: true
html_show_copyright: false
html_last_updated_fmt: '%B %-d, %Y'
html_static_path: ["images"]
bibtex_default_style: myapastyle
bibtex_reference_style: author_year_round
local_extensions:

2
book/external/Sphinx-TUDelft-theme vendored

@ -1 +1 @@
Subproject commit 0f4758586bebb1db4da0738b66d02d883ff7b54d
Subproject commit a7a87d4d4c9dc3839af49104492048724d1e6191

BIN
book/images/TB_logo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 544 KiB

BIN
book/images/TB_logo_dark.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 268 KiB

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

@ -36,18 +36,18 @@ A python virtual environment is, like the name might suggest, a reserved space w
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.
For simplicity we will call this environment `my_new_book_env`, 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)`
2. Execute: `conda create --name my_new_book_env pip` (this may take several minutes)
3. Activate: `conda activate my_new_book_env`
<br> Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book_env)`
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).
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 `teachbooks` which is a wrapper around JupyterBooks. More information about this package [here](jupyter-book-setup.md).
### Import environments
@ -121,7 +121,7 @@ If you want to create an environment based on an existing `*.yml` file, you can
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!
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_env` 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.
@ -135,7 +135,7 @@ If you have many projects, the amount of environments can take up a lot of space
To remove an environment, in your Anaconda Prompt, run:
`conda remove --name my_new_book --all`
`conda remove --name my_new_book_env --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:

410
book/workflows/edit_book.md
View file

@ -18,45 +18,50 @@ In GitLab, you can directly make changes in the files on the remote repository.
2. Create a new file by clicking on the plus button in the top bar. You can either create an entirely new file by clicking `New File` or if you already have created a file you can upload it by clicking `Upload File`.
```{figure} figures/User3_NewFile.PNG
---
width: 60%
align: center
---
Create new file
```
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repository by clicking the blue button `Commit changes`.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Edit new file
```
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the blue button called `Edit` and select the option `Edit single file`.
```{figure} figures/User3_EditFile.PNG
---
align: center
---
Web Editor
```
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the blue `Commit changes` button.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Commit changes
```
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as you did with markdown `file.md` files.
```{figure} figures/User3_toc.PNG
---
align: center
---
Table of contents (TOC)
```
``````
``````
``````{tab-item} ... GitHub...
`````{tab-set}
@ -88,36 +93,40 @@ Create new file
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `file_name.md`. Once you are done, commit the new file to the repository by clicking the green button `Commit changes`.
```{figure} figures/HubUser3_NewFile2.PNG
---
width: 80%
align: center
---
Edit new file
```
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the downward pointing arrow on the very left in the top bar. Select the option `Edit in place`.
```{figure} figures/HubUser3_EditFile.PNG
---
width: 80%
align: center
---
Edit in place
```
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the green `Commit changes` button.
```{figure} figures/HubUser3_EditFile2.PNG
---
width: 80%
align: center
---
Commit changes
```
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as with markdown `(file.md)` files.
```{figure} figures/HubUser3_toc.PNG
---
width: 80%
align: center
---
Table of contents
```
````
@ -157,52 +166,19 @@ name: user4_clone_edit_demo
Demonstration, video available [here](https://youtu.be/bThimdDRXTc)
```
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. Select the files ready to be added to Git-timeline (staging).
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.
```{include} stage_commit_push_vscode.md
```
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.
3. Adding changes to the Git-timeline (committing)
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.
4. 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
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
```{include} stage_commit_push_github_desktop.md
```
<figure align="center">
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
</figure>
3. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
4. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push origin` in the top bar.
<figure align="center">
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
</figure>
````
`````
``````
@ -219,7 +195,9 @@ After committing, click the 🔄 button to push our changes to the remote reposi
`````{tab-set}
````{tab-item} ... Git in VS Code
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
<figure align="center">
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
@ -227,7 +205,9 @@ After committing, click the 🔄 button to push our changes to the remote reposi
By clicking on the 🔄 button, you will pull your colleages' changes.
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
**Solving potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
<figure align="center">
<img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
@ -241,47 +221,28 @@ The figure above shows the conflicts. If you look closely you can see that the l
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. Select the 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.
```{include} stage_commit_push_vscode.md
```
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.
5. Adding changes to the Git-timeline (committing)
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.
6. 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
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
<figure align="center">
<img src="figures/Fetch.PNG" alt="Example Image" width="650">
</figure>
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
**Solving potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
<figure align="center">
<img src="figures/Conflicts1.PNG" alt="Example Image" width="650">
<img src="figures/Conflicts1.PNG" alt="Example Image" width="450">
</figure>
In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conflict directly in GitHub Desktop by choosing the branch of the file you want to keep.
@ -298,21 +259,10 @@ The figure above shows the conflicts. If you look closely you can see that the l
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
<figure align="center">
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
</figure>
5. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push origin` in the top bar.
<figure align="center">
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
</figure>
```{include} stage_commit_push_github_desktop.md
```
````
````{tab-item} ... using 'VS Code in your browser'
@ -351,151 +301,25 @@ name: user5_demo
Demonstration, video available [here](https://youtu.be/2ttjBevkEP8)
```
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. Once all the changes are made, it can be useful to check the changes locally on your device.<br />
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
```
conda activate jupyter-book-env
```{include} user45_check_changes.md
```
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} stage_commit_push_vscode.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
3. If you are satisfied with your changes, you can select the 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.
4. Adding changes to the Git-timeline (committing)
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.
5. Adding changes to GitLab/GitHub (pushing)
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/GitHub.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} ... GitHub Desktop
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. Once all the changes are made, it can be useful to check the changes locally on your device.<br />
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
```
conda activate jupyter-book-env
```{include} user45_check_changes.md
```
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} stage_commit_push_github_desktop.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging)
The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
```{figure} figures/Stage_GitHubDekstop.PNG
width: 50%
Staging
```
4. Add changes to Git-timeline locally (committing). In the field that says `Summary (Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push Origin` in the top bar.
```{figure} figures/Push_GitHubDekstop.PNG
width: 100%
Push origin
```
````
`````
``````
@ -513,7 +337,9 @@ Push origin
`````{tab-set}
````{tab-item} ... Git in VS Code
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
<figure align="center">
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
@ -521,7 +347,9 @@ Push origin
By clicking on the 🔄 button, you will pull your colleages' changes.
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
**Solve potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
<figure align="center">
<img src="figures/Conflicts2.PNG" alt="Example Image" width="600">
@ -535,85 +363,28 @@ The figure above shows the conflicts. If you look closely you can see that the l
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy!
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
`conda activate jupyter-book-env`
(or the environment in which you have installed the TeachBooks package)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} user45_check_changes.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```{include} stage_commit_push_vscode.md
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
5. Select the 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.
6. Adding changes to the Git-timeline (committing)
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.
7. 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
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
<figure align="center">
<img src="figures/Fetch.PNG" alt="Example Image" width="650">
</figure>
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
**Solve potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
<figure align="center">
<img src="figures/Merge_Conflict_GitHubDesktop2.PNG" alt="Example Image" width="400">
@ -623,63 +394,14 @@ In this case there are two conflicted files. GitHub Desktop is suggesting to res
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy!
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
`conda activate jupyter-book-env`
(or the environment in which you have installed the TeachBooks package)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} user45_check_changes.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```{include} stage_commit_push_github_desktop.md
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
5. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
<figure align="center">
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
</figure>
6. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
7. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push origin` in the top bar.
<figure align="center">
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
</figure>
````
````{tab-item} ... using 'VS Code in your browser'

BIN
book/workflows/figures/Push_GitHubDekstop.PNG Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

12
book/workflows/github_dev.md
View file

@ -4,20 +4,22 @@
4. In case you want to add a new file, navigate to the explorer file (the page icon) and click on the `New File` icon. This will create a new file in the folder that you are in. Give it the right extension!
```{figure} figures/Online_VS0.PNG
---
name: New File
width: 50%
align: center
---
New File
```
5. In case you want to make changes to an existing file, navigate to a file and make some changes.
```{figure} figures/Online_VS1.PNG
---
name: VS Code in Browser
width: 70%
align: center
---
VS Code in Browser
```
In the bottom left you can see the branch you are working in.
@ -26,19 +28,21 @@ In the bottom left you can see the branch you are working in.
7. Now let's see the result. Go back to your GitHub repo. In the top bar, go to actions.
```{figure} figures/Online_VS2.PNG
---
name: GitHub Actions
width: 70%
align: center
---
GitHub Actions
```
You will see the latest commit you just did (in this case text). After the pipeline has run, the yellow icon will turn green. Click on the commit and scroll until you see the title Deployed Branches.
```{figure} figures/Online_VS3.PNG
---
name: Deployed Branches
width: 60%
align: center
---
Deployed Branches
```
Click on the link and admire your changes:)

25
book/workflows/stage_commit_push_github_desktop.md Normal file
View file

@ -0,0 +1,25 @@
**Selecting changes to be added to the Git-timeline (staging)**
The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
```{figure} figures/Stage_GitHubDekstop.PNG
---
width: 50%
---
Staging
```
**Adding changes to the Git-timeline (committing)**
In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After you've done this, click the blue button `Commit to repository`.
**Adding changes to GitLab/GitHub (pushing)**
Now we need to add changes to GitHub/GitLab. This is called pushing to the remote repository. After committing, click on `Push origin` in the top bar.
```{figure} figures/Push_GitHubDekstop.PNG
---
width: 80%
---
Push origin
```

31
book/workflows/stage_commit_push_vscode.md Normal file
View file

@ -0,0 +1,31 @@
**Selecting changes to be added to the 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.
**Adding changes to the Git-timeline (committing)**
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.
**Adding changes to GitLab/GitHub (pushing)**
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/GitHub.
```{figure} ../images/git-push.png
---
After committing, click the 🔄 button to push our changes to the remote repository.
```

35
book/workflows/user45_check_changes.md
View file

@ -1,37 +1,34 @@
Once all the changes are made, it can be useful to check the changes locally on your device.
**Checking changes locally**
Once all the changes are made, it can be useful to check the changes locally on your device.
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
```
conda activate jupyter-book-env
conda activate my_new_book_env
```
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```
Alternatively:
Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
```
jupyter-book build <path-to-book> --all
```
Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} ../figures/buildbook.PNG
---
Output
```
Paste the last line into your browser to see the updated changes.
Paste the last line into your browser to see the updated changes.
```{Note}
@ -41,4 +38,4 @@ Sometimes there are problems building the book. It could be that the building re
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]