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

Moved stuff from install chapter and restructured

Browse source
This commit is contained in:
Tom van Woudenberg 2024-03-25 09:56:38 +01:00
parent 9b7034d4cd
commit 05f7e7e86a
12 changed files with 200 additions and 122 deletions
Download patch file Download diff file Expand all files Collapse all files

12
book/_toc.yml
View file

@ -10,11 +10,6 @@ parts:
- file: installation-and-setup/git-setup
- file: installation-and-setup/vscode-setup
- file: installation-and-setup/git-setup_local
sections:
- file: installation-and-setup/git-clone
- file: installation-and-setup/git-branch
- file: installation-and-setup/git-stage-commit-push
- file: installation-and-setup/git-merge
- file: installation-and-setup/anaconda
- file: installation-and-setup/add_conda_to_path
- file: installation-and-setup/working-directory
@ -23,7 +18,12 @@ parts:
- file: workflows/overview
sections:
- file: workflows/collaboration
- file: workflows/publish
sections:
- file: workflows/milestones_issues
- file: workflows/repositories
- file: workflows/branches
- file: workflows/edit_book
- file: workflows/publish
- file: workflows/githubtemplate
- caption: Features
chapters:

15
book/features/buildbook.md Normal file
View file

@ -0,0 +1,15 @@
# Book build on webserver / GitHub Pages
Now that we have talked about how you can collaborate using git, it's time to explain how the book is actually built.
## GitLab Pages
## GitHub Pages
## Pipeline
Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML.
Continuous Deployment ensures that the book is deployed onto the desired destination (in our case the website) and accessible to the readers.

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

@ -1,24 +0,0 @@
(git-clone)=
# Cloning a repository
Before we can start working on our Jupyter Book, we of course need to have the repository on our own system. This is done by *cloning* the repository, and here's how you do it with VS Code:
1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
The cloning menu.
```
2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository".
```{figure} ../images/vscode-welcome.png
:name: vscode-welcome
The VS Code welcome screen.
```
3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open".
4. You now have a local copy of the repository. Next, {ref}`make a new branch <git-branch>` for your work.

1
book/workflows/access_control_permissions.md Normal file
View file

@ -0,0 +1 @@
# Access Control / Permissions

30
book/installation-and-setup/git-branch.md → book/workflows/branches.md
View file

@ -1,15 +1,17 @@
(git-branch)=
# Branches
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. Some advantages of working with branches are:
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:
- Isolation: when you work on your own branch, your changes are isolated from the main codebase. Unfinished or unreviewed parts of your book are "hidden".
- Collaboration: branches make it easier for multiple project members to work on the same codebase simultaneously. If every member works on their own branch, they can make their changes without having to worry about interfering with another members' changes.
- Isolation: when you work on your own branch, your changes are isolated from the main codebase. Unfinished or unreviewed parts of your book are "hidden". Your own branch helps to keep an overview of the changes made to the book.
- Collaboration: branches make it easier for multiple project members to work on the same codebase simultaneously. If every member works on their own branch, they can make their changes without having to worry about interfering with another members' changes. In case those changes made in parallel lead to conflicts, they can be resolved during the merging of the branches.
## How to make a branch
This systematic workflow guarantees that editing the book goes smoothly.
The act of making a new branch from an existing one is called *branching*. Usually, you want to branch from the `main` branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the *source* branch.
`````{tab-set}
````{tab-item} Branching in GitLab
1. On GitLab, navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch".
```{figure} ../images/gitlab-branch.png
@ -33,9 +35,12 @@ 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} Branching locally with Git in VS Code
4. The final step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`).
```{figure} ../images/git-branch-menu-main.png
:name: git-branch-menu-main
@ -47,9 +52,10 @@ Location of the branch menu.
The branch selection menu, where our new branch has shown up.
```
````
````{tab-item} Branching locally with GitHub Desktop
...
````
`````
5. Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.
## The `publish` branch
If your repository is located in the [Interactive Textbooks CiTG](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.
Now that we've created and checked out our new branch, we can start {ref}`making and committing changes <stage-commit-push>`.

64
book/workflows/collaboration.md
View file

@ -1,54 +1,14 @@
# Collaboration
# Collaborative book-editing using Git
As previously mentioned there are multiple platforms that can host Git repositories. Here we will elaborate on two: GitLab and GitHub.
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.
## Staging, committing and pushing
A jupyter book is composed out of many markdown files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch. Find out for about staging committing and pushing [here](/book/installation-and-setup/git-stage-commit-push.md).
## Repositeries, Branching and Merging
We have previously introduced the notions of local and remote repositories, [branching](/book/installation-and-setup/git-branch.md). and finally [merging branches](/book/installation-and-setup/git-merge.md).
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`.
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.
- The different branches help to keep an overview of the changes made to the book.
- Branching allows multiple people to make changes to the book at the same time.
- In case those changes made in parallel lead to conflicts, they can be resolved during the merging of the branches.
This systematic workflow guarantees that editing the book goes smoothly.
Merging a branch into the main branch is a 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.
```{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.
```
## Access Control / Permissions
## Milestones & Issues
In a repository, team members can define Milestones and Issues. Milestones are used to track the overall progress of the project to make sure that deadlines are met. A milestone can group many issues, which are individual tasks that need to be finished in order to reach the milestone. Every team member can create issues when they think of a task that would improve the book like for example:
<img src="figures/Issues.png" alt="New Issue" width="1000" style="display:block; margin-left:auto; margin-right:auto;"> <br>
You can create an issue by clicking on the blue `New Issue` button in the top right corner.
An issue is built up of the following attributes:
- the title, this should just be a quick description of the task
- a label, to assign a category to the task such as: new content
- an assignee, the person who created the task can assign a team-member to the task or the task can remain without an assignee. Then whoever would like to pick up the task can assign it to themselves!
- a discussion section, here team-members can discuss any questions about the task
- a due date, in case the task is urgent or to keep track of deadlines
<img src="figures/New_Issue_GitLab.png" alt="New Issue" width="600" style="display:block; margin-left:auto; margin-right:auto;"> <br>
When the task is completed, the issue can be closed and you can move on to the next!
## Publishing the website
Once the book is ready to be published, a static website can be created through GitLab pages. (Need more info on that/Are we using gitlab pages?)
## GitHub
The workflow described above is largely the same on both platforms since both platforms stick to the names of the git functionalities. So alternatively to GitLab. Github and Github pages ca also be used to publish your book.
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
4. Edit the book by:
- 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

56
book/installation-and-setup/git-stage-commit-push.md → book/workflows/edit_book.md
View file

@ -1,9 +1,22 @@
(stage-commit-push)=
# Staging, committing and pushing
# Editing the book
A jupyter book is composed out of many markdown files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch.
Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes, and we've checked out this branch (make sure this is really the case by checking the name of the current branch in the bottom-left corner of your VS Code window!).
## Staging
`````{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
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
@ -12,8 +25,23 @@ The new file appears in the Source Control menu.
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
````
````{tab-item} Staging using GitHub Desktop
...
````
`````
## Committing
Now that we've made some change, we need to add them to our git-timeline.
`````{tab-set}
````{tab-item} Committing in GitLab
...
````
````{tab-item} Committing in GitHub
...
````
````{tab-item} Committing using Git in VS Code
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
@ -22,23 +50,29 @@ 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? No! 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. 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.
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.
```
## Summary
In short, the Git workflow consists of the following steps:
1. Staging new and modified files
2. Writing a commit message
3. Committing the changes
4. Pushing the new changes to GitLab
````
````{tab-item} Committing using GitHub Desktop
...
````
`````

20
book/installation-and-setup/git-merge.md → book/workflows/merge_request.md
View file

@ -1,8 +1,16 @@
(git-merge)=
# Merging
# Reviewing and merging changes
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.
```{note}
There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch.
```
We're finished with our chapter, and now it's time to include all of our commits in the `main` branch.
`````{tab-set}
````{tab-item} Committing using GitLab
1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository.
2. Go the repository overview on GitLab. In the left menu bar, go to "Merge requests". On the Merge requests page, click "New merge request".
@ -30,4 +38,10 @@ Example of a filled-in merge request.
:name: gitlab-finished-merge-request
The finished merge request.
```
```
````
````{tab-item} Committing using GitHub
...
````
`````

32
book/workflows/milestones_issues.md Normal file
View file

@ -0,0 +1,32 @@
# Milestones & Issues
In a repository, team members can define Milestones and Issues. Milestones are used to track the overall progress of the project to make sure that deadlines are met. A milestone can group many issues, which are individual tasks that need to be finished in order to reach the milestone.
An issue is built up of the following attributes:
- the title, this should just be a quick description of the task
- a label, to assign a category to the task such as: new content
- an assignee, the person who created the task can assign a team-member to the task or the task can remain without an assignee. Then whoever would like to pick up the task can assign it to themselves!
- a discussion section, here team-members can discuss any questions about the task
- a due date, in case the task is urgent or to keep track of deadlines
Every team member can create issues when they think of a task that would improve the book.
`````{tab-set}
````{tab-item} Issues 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>
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>
````
````{tab-item} Issues in GitHub
...
````
`````
When the task is completed, the issue can be closed and you can move on to the next!

2
book/workflows/overview.md
View file

@ -1,4 +1,4 @@
# Working in Git
# Workflows
- what does the publish branch do?
- what is a pipeline

15
book/workflows/publish.md
View file

@ -1,15 +1,4 @@
# Publishing your book
Now that we have talked about how you can collaborate using git, it's time to explain how the book is actually built.
# GitLab Pages
# GitHub Pages
# Pipeline
Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML.
Continuous Deployment ensures that the book is deployed onto the desired destination (in our case the website) and accessible to the readers.
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 [Interactive Textbooks CiTG](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.

51
book/workflows/repositories.md Normal file
View file

@ -0,0 +1,51 @@
# 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`.
If you'd like to work on your book locally, you need to clone your book.
### Cloning a repository
`````{tab-set}
````{tab-item} Cloning repository from GitLab
Here's how you do it with VS Code:
1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH".
```{figure} ../images/gitlab-clone.png
:name: gitlab-clone
The cloning menu.
```
````
````{tab-item} Cloning repository from GitHub
...
````
````{tab-item} Cloning repository from GitHub using GitHub Desktop
...
````
`````
Now that we've obtained the source, we can set up the files locally:
`````{tab-set}
````{tab-item} Cloning repository 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
:name: vscode-welcome
The VS Code welcome screen.
```
3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open".
4. You now have a local copy of the repository.
````
````{tab-item} Cloning repository with GitHub Desktop
....
````
`````