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

book/workflows/branches.md

@@ -38,7 +38,7 @@ Click the highlighted button to make a new branch.
 We're making a new branch called `chapter-2` from the `main` branch.
 ```
 
-3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch.
+3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch which is what we previously called `selecting an existing version`.
 
 ```{figure} ../images/gitlab-new-branch-repo.png
 :name: new-branch-repo
@@ -62,23 +62,35 @@ Tip: It makes sense to give the branch a name related to the content you will be
 
 ```{figure} ../figures/NewBranch_GitHub3.PNG
 ```
+4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).
+
+```{figure} ../figures/NewBranch_GitHub4.PNG
+```
 ````
 `````
 ````````
 
 ````````{tab-item} ... user type 4 and 5 ...
 
-**Select the statement that applies to you.**
+As user type 4 and 5, you make changes to the book locally on your computer rather than online on GitLab/GitHub. This allows you to create more complex and interactive sections to your book. Before you can start, there are a few preparatory steps you need to take. 
+
+**Cloning**
+
+In order to create your own version, you will first have to open the repositery. Then, you will need to clone the repositery to your computer. This procedure is called cloning.
+
+**Branching**
+
+If your repositery is already cloned on your computer, you are almost ready to start editing the book. However, remember that you are most likely not the only person making changes to the book. To keep an overview of the changes made by you and your colleages, it is important that changes are first made in a 'copy' of the book and are then merged into the final version. This is done through branching! You can create your version of the book by creating a new version (branch) or you can continue the work in an existing version (checkout branch). 
 
 ```````{tab-set}
 
-``````{tab-item} I am opening the repositery for the first time (Cloning)
+``````{tab-item} Cloning
 
-**I would like to open the repository locally (cloning) using ...**
+**1. Open the repository locally using ...**
 
 `````{tab-set}
 
-````{tab-item} ... GitLab ...
+````{tab-item} ... GitLab
 
 1. Navigate 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".
 
@@ -89,7 +101,7 @@ The cloning menu.
 ```
 ````
 
-````{tab-item} ... GitHub ...
+````{tab-item} ... GitHub
 
 1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
 
@@ -104,7 +116,7 @@ The cloning menu.
 </figure>
 ````
 
-````{tab-item} ... GitHub through GitHub Desktop ...
+````{tab-item} ... GitHub through GitHub Desktop
 
 1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called `<> Code`.
 
@@ -124,11 +136,11 @@ The cloning menu.
     <img src="figures/CloneRepo_TroughGithubdesk.PNG" alt="Example Image" width="400">
 </figure>
 
-You've cloned the repository now directly, so you can skip the next step.
+You have now directly cloned the repository, so you can skip the next step!
 ````
 `````
 
-**... and I would like to clone the local repositery with ...**
+**2. Clone the local repositery with ...**
 
 `````{tab-set}
 ````{tab-item} ... VS Code
@@ -169,12 +181,15 @@ The VS Code welcome screen.
 
 ````
 `````
+**You have now cloned the repositery to your computer and you can start branching. <br> 
+Have a look at the other section!**
 ``````
 
-``````{tab-item} I have previously opened the repository (Branching)
+``````{tab-item} Branching
 
-**I want to (1) update my repository (pulling) and <br>
-            (2) create my own version (branching) or select an existing version (checkout branch) using ...**
+**I want to... <br>
+(1) update my repository (pulling) and <br>
+(2) create my own version (branching) or select an existing version (checkout branch) using ...**
 
 `````{tab-set}
 ````{tab-item} ... Git in VS Code
@@ -225,9 +240,8 @@ Leave your changes (stashed) on your working branch, in this case I was working
 
 ````
 `````
+Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.
 ``````
 ```````
 ````````
 `````````
-
-Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.

book/workflows/edit_book.md

@@ -341,39 +341,65 @@ The new file has been staged, and we've written a Commit Message.
 ```
 Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 
 
-In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
+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.
 
-```{Error}
+```{Note}
 
 Missing from this chapter: startup python server.
+
+You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.md)
 ```
 ````
 
 ````{tab-item} ... GitHub Desktop
 
-1. Obtain updates from colleagues from GitLab/GitHub (pulling). This synchronizes the remote repositery with your local repositery on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'. 
+1.. Make some changes to a file in for example VS Code and save them.
 
-<figure align="center">
-    <img src="figures/Fetch.PNG" alt="Example Image" width="650">
-</figure>
+2. 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! 
 
-2. When multiple people work on one chapter, it is possible that conflicts will arise. This means that two users might have cheanged the same sections. GitHub Desktop will recognize this Solve potential incompatible changes (merging conflicts)
+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 actiavte the right environment. Type the following command:
 
-3. Make some changes to a file in for example VS Code and save them.
+`conda activate jupyter-book-env`
 
-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*. 
+(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 repositery in VS code and type the folloing command:
+
+`jupyter-book build book` 
+
+Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` 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`
+
+```
+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 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 Repositery`.
+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 Repositery`.
 
-6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
+5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repositery. After committing, the following screen will pop up. Click on `Push Origin`.
 
 <figure align="center">
     <img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
@@ -385,11 +411,12 @@ Alternatively, you can also click on `Push origin` in the top bar.
     <img src="figures/Push_GitHubDesktop2.PNG" alt="Example Image" width="650">
 </figure>
 
-```{Error}
+```{Note}
 
 Missing from this chapter: startup python server.
-```
 
+You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.html#view-the-book-using-a-local-webserver)
+```
 ````
 `````
 ``````

book/workflows/milestones_issues.md

@@ -40,6 +40,20 @@ Clicking on `Issues` will open up the page with all the issues on this repositer
 Finally, by clicking the green `New Issue` button you can create a new issue and specify all the attributes we mentioned before!
 
 <img src="figures/New_Issue_GitHub2.PNG" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
+
+```{Note}
+
+The follwing steps explain how to create a branch from a new issue. By doing this you can create most of the steps described in the section called [branching](branches.md). However, if you are unfamiliar with the term make sure to still read the section to understand the function.
+```
+After creating the issue, the description of the issue will automatically open. On the bottom left there is an option `create a branch` (in yellow) from this issue. This will create a new branch in the repositery which you can use to solve the issue. 
+
+<img src="figures/New_Issue_GitHub3.PNG" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
+
+Clicking on `create a branch` will open the following window in which you can specify the name and the repositery.
+
+<img src="figures/New_Issue_GitHub4.PNG" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
+
+```
 ````
 `````