admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

spring cleaning

Browse source
This commit is contained in:
Julie Kirsch 2024-12-05 23:16:37 +01:00
parent 6ad891252e
commit eca3ce5414
4 changed files with 119 additions and 351 deletions
Download patch file Download diff file Expand all files Collapse all files

383
book/workflows/edit_book.md
View file

@ -62,7 +62,6 @@ Table of contents (TOC)
```
``````
``````{tab-item} ... GitHub...
`````{tab-set}
@ -167,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>
````
`````
``````
@ -229,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">
@ -237,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">
@ -251,44 +221,25 @@ 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">
@ -308,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'
@ -361,153 +301,24 @@ 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:
```{include} stage_commit_push_vscode.md
```
teachbooks build <path-to-book>
```
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
```
````
`````
``````
@ -525,7 +336,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">
@ -533,7 +346,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">
@ -547,85 +362,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">
@ -635,63 +393,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'

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: 100%
---
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.
```

31
book/workflows/user45_check_changes.md
View file

@ -1,37 +1,40 @@
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.
**Checking changes locally**
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:
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.
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:
(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:
Alternatively:
```
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.
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 +44,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]